Single sign-on

Admin Portal

The Admin Portal is a hosted setup page for your customer's IT admin. You create a link for a tenant, send it to the admin, and they:

pick their identity provider,
follow the step-by-step instructions for it (the same ones as the SSO setup guides, with the ACS URL and entity ID for the tenant filled in),
paste the IdP metadata URL or XML,
get sent back to your app at the redirectUrl you chose.

The connection appears under the tenant in your dashboard as soon as they finish. The admin does not need an OrbitID account.

With your coding agent

Claude Code, Cursor or Codex makes the change in your repo and tells you what it touched.

Let our customers set up SSO themselves with the OrbitID Admin Portal. Follow https://orbitid.com/docs/admin-portal.md

1. On the organization settings page, add a "Set up SSO" button for org admins.
2. On click, POST /api/v1/portal/links from the server with tenant = the organization id, tenantName = its name, redirectUrl = this settings page, and its email domains.
3. Redirect the admin to data.url. Never send ORBITID_API_KEY to the browser.
4. Show "SSO connected" once GET /api/v1/sso?tenant=<id> returns a connection.
5. Run the tests, then list the files you changed.

Create a link

In the dashboard, open Connections and click Create setup link, or call the API:

curl -X POST https://app.orbitid.com/api/v1/portal/links \
  -H "Authorization: Bearer orb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tenant": "acme",
    "tenantName": "Acme Inc.",
    "redirectUrl": "https://yourapp.com/settings/sso",
    "domains": ["acme.com"]
  }'

Field	Required	Description
`tenant`	yes	Your identifier for the customer. Use the same value when you start logins.
`tenantName`	yes	Shown to the admin in the portal, for example the company name.
`redirectUrl`	yes	Absolute URL the admin is sent to when they finish.
`domains`	no	Email domains the customer must verify before the connection goes live.
`connectionName`	no	Name of the connection that gets created. Defaults to `tenantName`.
`fromUrl`	no	Absolute URL of the page in your app the admin came from, used for a back link.
`expiresInMinutes`	no	How long the link is valid.

The response is 201 Created with the link:

{
  "data": {
    "id": "6f1c0b2d…",
    "url": "https://app.orbitid.com/portal/6f1c0b2d…",
    "tenant": "acme",
    "tenantName": "Acme Inc.",
    "redirectUrl": "https://yourapp.com/settings/sso",
    "connectionName": "Acme Inc.",
    "domains": ["acme.com"],
    "verifiedDomains": [],
    "createdAt": 1726900000000,
    "expiresAt": 1727000000000
  }
}

Send data.url to the admin. A link is tied to one tenant and stops working after expiresAt; create a new one if it expires before the admin gets to it.

Domain verification

Pass domains when you want proof that the customer controls the email domains their users will sign in with. This protects you from a tenant claiming another company's domain.

When a link has domains, the portal asks the admin to add a DNS TXT record for each domain. The record name and value are shown in the portal; the value has the form orbitid-domain-verification=<tenant>:<domain>. Once the record resolves, the admin clicks Verify and the domain moves from domains to verifiedDomains. The connection is only activated when every domain is verified.

To send the admin straight to the verification step, create the link with POST /api/v1/portal/verify-domain instead. It takes the same body and additionally returns verifyDomainUrl.

After the admin finishes

The connection is created under the tenant, in the environment the API key belongs to.
In Production it is billed like any other connection. See Billing.
You can test it immediately by starting a login for the tenant as described in the quickstart.