---
title: Migrating from WorkOS
description: 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](https://github.com/VortexNYC/convex-auth/issues).

## Concept mapping

| WorkOS                                      | convex-auth                                                                                                                      |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| AuthKit hosted sign-in                      | Drop-in auth pages — [UI components](/convex-auth/components)                                                                               |
| `getAuthorizationUrl()` + callback          | `signIn.social` / OAuth flow — [OAuth](/convex-auth/oauth)                                                                                  |
| Enterprise SSO (Okta, Entra, …)             | [Generic OAuth](/convex-auth/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](/convex-auth/organizations) with roles and invitations                                                                      |
| API keys (machine auth)                     | [API keys](/convex-auth/api-keys) and [service principals](/convex-auth/service-principals)                                                            |
| WorkOS Events / webhooks                    | [Webhooks](/convex-auth/webhooks) — signed, with replay protection                                                                          |
| Session cookies via `@workos-inc/authkit-*` | Framework adapters — [Next.js](/convex-auth/nextjs), [TanStack Start](/convex-auth/tanstack-start)                                                     |
| Directory Sync (SCIM)                       | Not built today — [OIDC provider](/convex-auth/oidc-provider) covers the "your app as IdP" direction                                        |

## The cutover path

1. **Stand up convex-auth** in staging — [Quickstart](/convex-auth/quickstart). If you used WorkOS for SSO, configure each enterprise IdP under [Generic OAuth](/convex-auth/generic-oauth) and verify the provider accepts your new callback URLs (`https://<your-deployment>.convex.site/api/auth/callback/<provider>`).
2. **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.
3. **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](https://github.com/VortexNYC/convex-auth/issues).
4. **Re-register SSO connections.** Each enterprise connection that speaks OIDC becomes a [Generic OAuth](/convex-auth/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.
5. **Cut over the client.** Replace the AuthKit SDK calls with the auth client (`useConvexAuthClient()` gives you `signIn.social`, `signOut`, and the rest; `useSession()` tracks auth state) — the [React guide](/convex-auth/react) 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](/convex-auth/webhooks) can feed your own audit sink.

## Get help

SSO cutovers have real customer-facing lead time — the [troubleshooting](/convex-auth/troubleshooting) page covers callback and session issues, and GitHub issues get answered.