Migrating from Clerk
Concept mapping and the manual cutover path from Clerk to convex-auth.
Moving from Clerk to convex-auth means your users, sessions, organizations, and UI all move into your Convex deployment — there is no hosted middle tier left. There is no turnkey importer today; this page maps the concepts and lays out the cutover path. If you want a scripted importer, open an issue.
Concept mapping
| Clerk | convex-auth |
|---|---|
<ClerkProvider> |
ConvexAuthClientProvider — see the React guide |
<SignIn /> / <SignUp /> |
ConvexAuthSignInPage / ConvexAuthSignUpPage — UI components |
useAuth() / useUser() |
useSession() / useConvexAuthUser(authClient) — React guide |
auth() in middleware.ts |
Next.js adapter middleware — Next.js guide |
| Organizations, memberships, roles | Organizations — first-class tables, roles, invitations |
<OrganizationSwitcher /> |
ConvexOrganizationSwitcher — UI components |
| Sessions list / “Devices” | ConvexSessionList — UI components |
| Webhooks (user.created, …) | Webhooks — signed lifecycle events |
| Backend API keys | None — Clerk secret keys are Clerk’s own API credentials. The convex-auth API keys feature issues keys for your API instead |
| JWT templates | Native Convex JWTs — see Architecture |
The cutover path
- Stand up convex-auth alongside Clerk: mount the component, wire
convex/auth.ts, and point a staging app at it. Follow the Quickstart. - Export users from Clerk (Dashboard → Users → export, or the Backend API). You get emails, names, and optionally bcrypt password hashes.
- Import users. Component tables are isolated — your app’s functions can’t
ctx.db.insertinto them, so there is no direct-write path. Today the only shipped importer is the Better Auth path (pnpm dlx @vortex-api/convex-auth migrate better-auth); amigrate clerkcommand does not exist yet — open an issue if you need it. In the meantime, the pragmatic path is just-in-time: users sign up fresh with the same email on first visit (OAuth and magic links make this painless), and you reconcile org membership out-of-band. - Passwords need a reset. Clerk stores bcrypt hashes and convex-auth verifies argon2id, scrypt (Better Auth-compatible), and pbkdf2 formats — bcrypt is not one of them. Imported users sign in via forgot password, OAuth, or a magic link. Communicate this in the cutover email.
- Recreate organizations. Map Clerk orgs and memberships onto the
convexAuthOrganizationstables, preserving role names where possible. - Cut the client over route by route — Clerk middleware off, the adapter’s middleware on. Old Clerk session tokens die with the provider, so plan a single sign-out event.
What does not migrate
- Active sessions — every user signs in once more.
- Clerk TOTP secrets and passkeys — users re-enroll (migrated users land with 2FA off, so nobody is locked out).
- Clerk’s hosted UI session handling, device tracking granularity, and enterprise SSO connections — SSO providers become Generic OAuth configs.
Get help
The migration surface is the most common place teams need a second pair of eyes — the troubleshooting page covers the cutover failure modes, and GitHub issues get answered.