Skip to content
Dashboard
Theme
Theme

WorkOS SSO compatibility

Use the implemented compatibility bridge and understand its support policy.

View Markdown

The API host mounts GET authorize, POST token and GET profile at both /sso/authorize, /sso/token, /sso/profile and /compat/workos/sso/authorize, /compat/workos/sso/token, /compat/workos/sso/profile. This page covers the SSO bridge. Directory Sync compatibility has separate directory reads (prefixed and unprefixed) and webhook formatting; neither is a complete replacement for every WorkOS API. It requires the global compatibility gate and the environment compatibility setting to be enabled.

Use the environment’s live pk_ publishable key as client_id; an old WorkOS client ID is not an OhAuthCat client registry entry. Authorize accepts the supported connection or organization selector, an allowlisted redirect_uri, response_type=code and optional state. A nonempty provider selector is refused. Connection and organization selectors are mutually exclusive.

The bridge creates internal PKCE and seals the selected client, exact redirect and compatibility purpose into the flow. Native OhAuthCat flows retain caller PKCE. Codes and tokens from the two purposes are not interchangeable.

Exchange the code using grant_type=authorization_code, client_id, code and the same environment’s sk_ secret as client_secret. The secret must have sso:exchange; an optional Bearer secret must match the supplied client secret. Token authentication is the client secret, not an ordinary management-API key header alone. Profile uses the compatibility access token as a Bearer token. The token response contains access_token, token_type, expires_in and the normalized profile. Imported legacy IDs preserve supported WorkOS identity mapping; configuration still needs a tested active connection.

Changing an SDK base URL alone does not configure keys, selectors, redirect allowlists or the environment gate. Local official-SDK interoperability was tested against owned fixtures; no hosted WorkOS tenant or deployed compatibility service is asserted here.

  • Enable both compatibility gates for the intended environment.
  • Replace the old client ID with that environment’s live publishable key, configure our API hostname and use its secret key for token exchange.
  • Register the exact application redirect, and verify the selected connection’s metadata, domains, passing test and activation.
  • Test authorize, code exchange and profile together. Keep native token/profile calls on the broker auth host; these compatibility aliases are on the API host.
  • Preserve supported legacy organization, connection and profile IDs within their imported environment. An ID is not permission to access another environment.

Compatibility does not move application sessions or change the IdP’s ACS settings. Plan those separately using session cutover and migration levers.

Compat nudge emails link here. Compatibility is a bridge; the Node and Python SDKs are the destination. Move one environment at a time and keep the compat routes running until the SDK path has passed the same tests.

  1. Install the SDK build supplied for your checkout (@ohauthcat/node or ohauthcat), and construct the client with the environment’s secret key, publishable key and environment ID: Node new OhAuthCat({ apiKey, clientId, environmentId }), Python OhAuthCat(api_key=..., client_id=..., environment_id=...). The publishable pk_ key replaces the WorkOS client ID; it is configured on the client, not passed per call.
  2. Replace the authorize call. WorkOS sso.getAuthorizationUrl(...) / sso.get_authorization_url(...) becomes Node client.sso.getAuthorizationUrl({ redirectUri, state, organization }) or Python client.sso.get_authorization_url(redirect_uri=..., state=..., organization=...). connection, domain and loginHint / login_hint are the other selectors. The result carries url and a fresh codeVerifier / code_verifier.
  3. Store the state and code verifier in your server-side session. The compat bridge generated PKCE for you; the SDK flow uses your verifier, so the callback cannot complete without it.
  4. Replace the code exchange. WorkOS sso.getProfileAndToken(...) / sso.get_profile_and_token(...) becomes Node client.sso.getProfileAndToken({ code, codeVerifier, redirectUri }) or Python client.sso.get_profile_and_token(code=..., code_verifier=..., redirect_uri=...), after you compare the callback state. The result has access_token, token_type, expires_in and profile. The exchange is never retried automatically; a RestartSignIn error means start a new sign-in.
  5. Replace profile reads. Verify the access token locally with client.sso.verifyAccessToken(token) / verify_access_token(token), or call getSsoProfile({ accessToken }) / get_sso_profile(access_token=...) when you need the server-side check.
  6. Replace Directory Sync reads with the native directory methods, for example client.directories.listDirectories(...) and listDirectoryUsers({ path: { dir } }), or list_directories(...) and list_directory_users(path={"dir": ...}) in Python. Native webhooks use the native event shapes; see Directory Sync compatibility for what differs.
  7. Deploy, test sign-in for each connection and confirm in the dashboard that compat usage for the environment’s keys has stopped.

Imported legacy organization, connection and profile IDs stay valid on the native API within their environment. The complete, tested sign-in programs are in the Node and Python quickstarts.

The support window starts at an environment’s first compat call.

Period Support Compat calls
Months 1–3 Standard, no compat charge Served
Months 4–6 Standard, no compat charge Served with Deprecation and Sunset headers
Months 7–12 Extended support add-on, $100/month (excl. taxes) Served with the add-on; otherwise compat_support_expired (410)
Months 13–18 Extended support add-on, $250/month (excl. taxes) Served with the add-on; otherwise compat_support_expired (410)
After month 18 None Always compat_support_expired (410)

From month 4 the compat SSO routes send Deprecation (RFC 9745, the end of standard support as @<unix seconds>) and Sunset (RFC 8594, the date compat stops for you: the end of month 6, or the end of month 18 with the add-on). Outside the window they answer compat_support_expired with status 410. Extended support is a paid add-on on top of your plan, bought in the dashboard under Settings > Billing; it cannot extend compat past month 18. Owners and admins get one email at each stage, linking to this page.

Plan the application API cutover separately from IdP migration and keep rollback controls available during verification.