# WorkOS SSO compatibility

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](/directory-sync/workos-compat/) 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.

## Bind the flow to one environment

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.

## Before moving an application

- 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](/migrate/session-cutover/) and [migration levers](/migrate/levers/).

## Switch to the SDK

Compat nudge emails link here. Compatibility is a bridge; the [Node](/get-started/quickstart-node/) and [Python](/get-started/quickstart-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](/directory-sync/workos-compat/) 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.

## Support policy

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`](/errors/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](/migrate/from-workos/) and keep [rollback controls](/migrate/cutover-and-rollback/) available during verification.
