Let your customer set up SSO

Setting up enterprise SSO for a business customer usually means passing certificates and URLs back and forth with their IT admin. Instead, send the IT admin a setup link. It opens the setup portal on your sign-in page, with your branding and domain. There they choose their identity provider, follow its steps, enter its details and run a test sign-in that proves the connection works. They need no account.

The portal is useful when you move from another provider, such as Auth0: send each business customer a setup link, and their IT admin points their identity provider at you.

Sending a setup link

1. Open Admin UI → Tenants → (select tenant) → Organizations and the customer's organization. Add it first if it isn't there, with its email domains.
2. Under Single sign-on, click Create setup link. Copy the link: it is shown once.
3. Send it to the customer's IT admin.

To create the link from your own backend, call POST /management/v1/tenants/{tenant_id}/organizations/{organization_id}/portal-links with an account API key that has the portal-links:write scope, or use the create_portal_link MCP tool. Your app can then send a signed-in admin of your customer straight to the link.

A link works for 7 days and can be opened more than once, so the IT admin can come back to it or pass it to a colleague. Creating a new link revokes the previous one, and Revoke link ends it at once, along with the portal sessions it opened.

What the IT admin can do

The portal reaches one organization and its enterprise connection only. In it, the IT admin can:

• choose their identity provider: Microsoft Entra ID, Okta or another provider, over SAML or OpenID Connect, with steps for Entra ID and Okta
• give their identity provider what it needs: for SAML a metadata file to upload, or the reply URL and identifier to enter by hand (Okta can't import a metadata file, so the portal shows those two values under Okta's own field names); for OpenID Connect the redirect URI
• go back and choose another provider or protocol, until the connection has been on
• enter the details their identity provider gives back: for SAML its metadata URL or metadata file, or its sign-on URL, entity ID and signing certificate by hand; for OpenID Connect its discovery URL, client ID and client secret
• save and run a test sign-in in one step and see what their identity provider sent and how it was read
• turn the connection off

They can't change the organization's email domains, delete the connection, or see any other organization. Only a passing test sign-in turns the connection on from the portal. See Testing an enterprise connection.

When the IT admin changes the settings of a connection that has passed its test, the change waits until a new test passes, and sign-in keeps working with the previous settings meanwhile.

Following progress

The organization's page and the Organizations tab show the connection's status. A connection still in Draft is waiting for the IT admin to finish and test it.

Everything the IT admin does in the portal is in Activity, named after the organization's setup link: creating, changing or removing the connection, each test sign-in and its outcome, and turning the connection off.