Migrating from WorkOS
Concept mapping and the manual cutover path from WorkOS AuthKit to convex-auth.
WorkOS sells you the authentication protocol surface — SSO, directory sync, the AuthKit hosted flow — while keeping user state in their cloud. convex-auth moves the same capability set into your Convex deployment. There is no turnkey importer today; this page maps the concepts and the cutover path. If you want a scripted importer, open an issue.
Concept mapping
| WorkOS | convex-auth |
|---|---|
| AuthKit hosted sign-in | Drop-in auth pages — UI components |
getAuthorizationUrl() + callback |
signIn.social / OAuth flow — OAuth |
| Enterprise SSO (Okta, Entra, …) | Generic OAuth — OIDC/OAuth2 only. No SAML path today; a SAML-only customer cannot migrate that connection |
| Users + identities | Users, identities, sessions in the convexAuth tables |
| Organizations + memberships | Organizations with roles and invitations |
| API keys (machine auth) | API keys and service principals |
| WorkOS Events / webhooks | Webhooks — signed, with replay protection |
Session cookies via @workos-inc/authkit-* |
Framework adapters — Next.js, TanStack Start |
| Directory Sync (SCIM) | Not built today — OIDC provider covers the “your app as IdP” direction |
The cutover path
- Stand up convex-auth in staging — Quickstart. If you used WorkOS for SSO, configure each enterprise IdP under Generic OAuth and verify the provider accepts your new callback URLs (
https://<your-deployment>.convex.site/api/auth/callback/<provider>). - Export users from the WorkOS dashboard or API — you get identities, emails, and org memberships. WorkOS does not export passwords (most AuthKit users authenticate via SSO or magic links anyway), so this is rarely a blocker.
- Import users and orgs. Component tables are isolated — your app’s functions can’t write them directly, and there is no shipped importer for WorkOS data. The pragmatic path is just-in-time signup on first visit (SSO users keep the same email at the IdP, so the OAuth account links cleanly), with org membership reconciled out-of-band. If you need a scripted importer, open an issue.
- Re-register SSO connections. Each enterprise connection that speaks OIDC becomes a Generic OAuth config — a new client registration at the IdP, so plan lead time with your customers’ IT teams before cutover. SAML-only connections have no target today.
- Cut over the client. Replace the AuthKit SDK calls with the auth client (
useConvexAuthClient()gives yousignIn.social,signOut, and the rest;useSession()tracks auth state) — the React guide maps the hooks.
What does not migrate
- Active sessions and WorkOS session cookies.
- SCIM / Directory Sync — there is no equivalent today; HR-driven provisioning stays manual or moves to your own sync via the API.
- Audit Trails (WorkOS’s hosted audit UI) — auth events land in your Convex tables instead, and webhooks can feed your own audit sink.
Get help
SSO cutovers have real customer-facing lead time — the troubleshooting page covers callback and session issues, and GitHub issues get answered.