← Back to guides

Migrate from Clerk to Own Auth

To migrate from Clerk to Own Auth, export users from the Clerk Dashboard or Backend API, import identity records without trusting incompatible session tokens, and require a verified account claim before transferring application data. Clerk can include hashed passwords in Dashboard exports, but the safest portable path is a magic-link claim followed by an Own Auth password reset.

Clerk migration is an identity cutover. Inventory users, login methods, application foreign keys, active sessions, organisations, and recovery flows.

Export and inventory Clerk users

  1. Export all users from Clerk instance settings and retain the export history record.
  2. Use Clerk's Backend API only when the migration needs fields that are not present in the CSV.
  3. Record primary email IDs, verification state, external IDs, organisation memberships, disabled state, and authentication methods.
  4. Separate development and production instances. Clerk does not support treating a development instance as the production user source.

Account transition

Own Auth creates new passwords with Argon2id and verifies only its documented hash formats. Do not copy an arbitrary provider password digest into Own Auth tables. The portable default is to create a passwordless user, verify control of the email address with a single-use magic link, and let the user set a new password through the password-reset flow.

  • Clerk sessions and cookies are not Own Auth sessions and must be replaced.
  • OAuth identities need a new provider flow using the application's own credentials.
  • Organisation roles must be mapped explicitly instead of inferred from names.
  • A Clerk password digest should not be inserted into Own Auth through undocumented storage fields.
scripts/import-users.ts
await auth.createUser({
  email: exportedUser.email,
  name: exportedUser.name ?? undefined,
  metadata: {
    migrationSource: "clerk",
    legacyUserId: exportedUser.id,
  },
});

Run imports through a server-only script with an idempotent legacy-ID mapping. Do not call this from a public route. Reconcile source and destination counts, duplicate emails, disabled accounts, and failures before sending any claim links.

Move application ownership safely

Keep the old provider ID in an application-owned mapping table until every foreign key and background job uses the Own Auth user ID. A matching email string is not enough to attach billing records, private content, or organisation membership. Require a verified claim before transferring access.

  1. Create Own Auth tables in the staging and production databases with the official migration command.
  2. Import disabled or deleted status separately so blocked accounts do not regain access.
  3. Create an explicit legacy-provider-ID to Own-Auth-user-ID mapping.
  4. Send claim links in controlled batches and rate-limit the claim endpoint.
  5. Transfer application records only after the claim succeeds.
  6. Keep an audit record of imported, claimed, skipped, and failed accounts without logging tokens or passwords.

Session replacement

Clerk manages hosted sessions and application cookies around its own session identifiers. Those sessions cannot be converted into Own Auth database sessions. Expect users to complete a claim link or sign in again, then issue a new opaque Own Auth session token through the application backend.

Use different cookie names during a short parallel window. Validate each cookie only with the system that issued it. Never accept an old provider token as an Own Auth session token, and remove the legacy validation path after the announced migration window.

Cutover and rollback

  1. Freeze authentication configuration changes while taking the final export.
  2. Run the idempotent import and reconcile counts.
  3. Enable Own Auth sign-in and recovery for a small internal cohort.
  4. Monitor sign-in failures, claim completion, email delivery, and support requests.
  5. Switch new sign-ins to Own Auth while retaining a time-limited rollback path.
  6. Revoke old provider sessions and credentials only after the cutover is stable.
  7. Delete encrypted working exports according to the migration retention plan.

The successful end state is not two permanent auth systems. Clerk becomes read-only during the transition, Own Auth becomes the only issuer of new sessions, and the legacy path is removed after account recovery and data reconciliation are complete.