How the SSO flow works
The end-to-end flow: your app redirects the user to /sso/authorize with PKCE, the broker resolves the organization's active connection and talks to the IdP, then redirects back with a single-use code that your server exchanges at POST /v1/sso/token.
Authorization, callback and exchange
Section titled “Authorization, callback and exchange”- Your server creates a random state value and a PKCE verifier. Store them with the initiating browser session, expected organization, exact redirect URI and a short expiry.
- Redirect the browser to
https:with the publishable/ / auth. ohauthcat. com/ sso/ authorize client_id,response_type=code, state, S256 challenge and a routing hint. - The broker selects an active, tested connection and performs SAML or OIDC validation with the IdP. It verifies the returned email against the organization’s verified domains.
- On your callback, reject repeated parameters, missing or mismatched state, the wrong browser session and expired attempts. Atomically consume the stored attempt before exchanging its code.
- Your server calls
POST https:, authenticating with the environment’s secret key and sending/ / auth. ohauthcat. com/ v1/ sso/ token grant_type=authorization_code,client_id,code,code_verifierand the exactredirect_uri. - Check the returned profile’s organization, map it to an allowed local identity and create your own session.
Token exchange and GET /v1/sso/profile run on the auth host. The management API host returns not_implemented for these operations. Browser-facing routes are unversioned; server-to-server exchange uses /v1/.
Single-use credentials
Section titled “Single-use credentials”Authorization codes expire after 60 seconds. A second exchange returns invalid_grant and revokes the token from the first exchange at the profile endpoint. Restart sign-in after an interrupted or invalid grant; do not keep retrying the old code. Broker state is sealed, bound to the flow and single-use; your application’s state check is still required.
The response contains an ES256 access token with a 600-second lifetime and a profile. Use the Node SDK’s sso. with the correct clientId, environmentId and issuer when verifying a token. A local signature check does not query broker revocation state; the profile endpoint checks the token’s current validity. Do not hand-decode a JWT and treat its claims as verified.
See sign-in errors and the SSO API reference.