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

## Concept mapping

| Clerk                             | convex-auth                                                                                                                                 |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `<ClerkProvider>`                 | `ConvexAuthClientProvider` — see the [React guide](/convex-auth/react)                                                                                 |
| `<SignIn />` / `<SignUp />`       | `ConvexAuthSignInPage` / `ConvexAuthSignUpPage` — [UI components](/convex-auth/components)                                                             |
| `useAuth()` / `useUser()`         | `useSession()` / `useConvexAuthUser(authClient)` — [React guide](/convex-auth/react)                                                                   |
| `auth()` in `middleware.ts`       | Next.js adapter middleware — [Next.js guide](/convex-auth/nextjs)                                                                                      |
| Organizations, memberships, roles | [Organizations](/convex-auth/organizations) — first-class tables, roles, invitations                                                                   |
| `<OrganizationSwitcher />`        | `ConvexOrganizationSwitcher` — [UI components](/convex-auth/components)                                                                                |
| Sessions list / "Devices"         | `ConvexSessionList` — [UI components](/convex-auth/components)                                                                                         |
| Webhooks (user.created, …)        | [Webhooks](/convex-auth/webhooks) — signed lifecycle events                                                                                            |
| Backend API keys                  | None — Clerk secret keys are Clerk's own API credentials. The convex-auth [API keys](/convex-auth/api-keys) feature issues keys _for your_ API instead |
| JWT templates                     | Native Convex JWTs — see [Architecture](/convex-auth/architecture)                                                                                     |

## The cutover path

1. **Stand up convex-auth** alongside Clerk: mount the component, wire `convex/auth.ts`, and point a staging app at it. Follow the [Quickstart](/convex-auth/quickstart).
2. **Export users from Clerk** (Dashboard → Users → export, or the Backend API). You get emails, names, and optionally bcrypt password hashes.
3. **Import users.** Component tables are isolated — your app's functions can't `ctx.db.insert` into 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`); a `migrate clerk` command does not exist yet — [open an issue](https://github.com/VortexNYC/convex-auth/issues) 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.
4. **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](/convex-auth/email-password), OAuth, or a [magic link](/convex-auth/magic-links). Communicate this in the cutover email.
5. **Recreate organizations.** Map Clerk orgs and memberships onto the `convexAuthOrganizations` tables, preserving role names where possible.
6. **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](/convex-auth/generic-oauth) configs.

## Get help

The migration surface is the most common place teams need a second pair of eyes — the [troubleshooting](/convex-auth/troubleshooting) page covers the cutover failure modes, and GitHub issues get answered.