← Back to guides

Migrate from Better Auth to Own Auth

To migrate from Better Auth to Own Auth, inventory the installed plugins and database schema, import identity records through supported Own Auth APIs, and replace Better Auth sessions with verified Own Auth account claims. Do not copy password digests or session rows into undocumented Own Auth tables.

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

Export and inventory Better Auth users

  1. Take an encrypted backup of the production database before reading authentication records.
  2. Record the installed Better Auth version, database adapter, configured plugins, and any customised table or column names.
  3. Export stable user IDs, primary emails, verification state, disabled state, creation dates, and application-owned profile fields.
  4. Inventory account providers, organisations, members, roles, passkeys, two-factor settings, and other plugin-owned records separately.

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.

  • Better Auth password digests are not automatically a supported Own Auth import format.
  • Better Auth session tokens and cookies must not be accepted as Own Auth sessions.
  • Plugin data needs an explicit mapping to supported Own Auth workflows or application-owned tables.
  • OAuth accounts must be re-established through a provider flow that the application backend verifies.
scripts/import-users.ts
await auth.createUser({
  email: exportedUser.email,
  name: exportedUser.name ?? undefined,
  metadata: {
    migrationSource: "better-auth",
    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

Better Auth and Own Auth use different session records, cookies, and validation paths. Keep the old session validator isolated during a short transition, require a verified claim or a fresh sign-in, and issue a new opaque Own Auth session token from the backend. Do not copy old session rows or reinterpret a Better Auth token.

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. Better Auth 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.