Migrate from Better Auth

Move a Better Auth deployment to Authdog while preserving application foreign keys and access relationships stored in your database. This guide covers schema inventory, stable IDs, credential handling, organizations, application cutover, rollback, and validation.

Prerequisites

• An Authdog tenant, project, and environment for staging rehearsal.
• Read access to the Better Auth database and source configuration, including enabled plugins and any customized table/field names.
• An inventory of every application using Better Auth client/server APIs, cookies, middleware, callbacks, hooks, and session fields.
• A database backup and tested restore procedure before migration writes begin.

Migration shape

1. Inventory and export — document actual schema, users, accounts, organizations, plugins, and session consumers.
2. Map and import — preserve Better Auth user IDs and recreate access in Authdog.
3. Parallel run — validate controlled cohorts while Better Auth remains available.
4. Cut over and retire — switch session authority, soak, then remove old credentials and code.

1. Inventory Better Auth

Better Auth schemas vary by database adapter, version, plugins, and custom model mappings. Inspect deployed schema rather than assuming default names.

Also identify every foreign key in application tables that references the Better Auth user or organization ID. Record current sign-up policy, email delivery, OAuth redirect URLs, secrets, and session cookie settings.

2. Export users and related records

Export from a transactionally consistent database snapshot. Retain:

• Better Auth user ID as stable source identifier
• Email, emailVerified, name, image, and timestamps
• Account provider and provider account identifiers
• Password credential fields, including algorithm metadata when present
• Banned, deleted, or inactive state
• Organization IDs, memberships, roles, invitations, and team relationships
• Application metadata and plugin-owned fields still needed after cutover

Store Better Auth user ID as the Authdog external identifier. Keep mapping tables for Better Auth organization IDs and Authdog organization IDs. Preserving source IDs avoids rewriting application rows immediately; do not rely on mutable email or organization name for joins.

Password strategy

Database access does not guarantee Authdog can verify stored passwords:

• Compatible hash import — use only after identifying exact algorithm, variant, parameters, salt/pepper requirements, and encoding, then confirming Authdog support in staging.
• Progressive migration — verify against the existing Better Auth server once, then establish the Authdog credential through a secure backend flow.
• Reset or passwordless — use password reset, magic link, OAuth, or SSO when credential material is incompatible.

If hashes depend on an application pepper, KMS key, or custom plugin, preserve that dependency only for the migration bridge and remove it after soak. Never export raw passwords. Treat sessions, passkeys, TOTP secrets, and recovery codes as non-portable unless explicitly verified.

3. Map organizations, roles, and providers

Create Authdog organizations first, then import memberships. Map Better Auth member roles to Authdog roles and permissions; represent plugin teams as roles, metadata, or application resources based on their authorization meaning.

Recreate OAuth and enterprise SSO connections using Authdog callbacks. Link identities by verified email only after checking duplicate and unverified records. Preserve provider account IDs when application/audit logic needs them.

Move custom session enrichment and hooks to Authdog metadata, roles, integrations, or backend logic after session validation. Do not copy stale authorization fields from old sessions.

4. Import and update applications

Import through console tooling or the REST Directory API:

1. Upsert profile and verification state.
2. Set Better Auth user ID as external identifier.
3. Attach needed metadata and suspend blocked users.
4. Create organizations, memberships, and mapped roles.
5. Link supported providers and record credential migration state.

Replace Better Auth client/server calls and middleware with Authdog (quickstarts). Configure the environment public key (pk_...), update callbacks and cookie expectations, and validate Authdog sessions on backends. Update application joins to resolve Authdog users through the preserved external ID or an explicit mapping table. See Backend requests.

5. Stage cutover and rollback

1. Restore a production snapshot into a safe rehearsal environment and run full import.
2. Validate password/provider login, foreign-key joins, organizations, and authorization.
3. Freeze identity schema changes; capture and replay user/membership deltas.
4. Move internal users, then one app or cohort.
5. Keep old/new session acceptance temporary, instrumented, and issuer-specific.
6. After soak, stop Better Auth writes, revoke provider/app secrets, and remove old session code.

Rollback: route users to Better Auth and restore its session middleware. Keep database backup plus migration/delta logs. Do not roll back imported application writes blindly; reconcile by stable source ID and timestamp.

Validation checklist

• Consistent snapshot and restore procedure tested.
• User/account/org/membership counts reconcile.
• Every Better Auth user ID remains a stable external identifier.
• Application foreign-key joins resolve correctly.
• Password path works without assumed hash compatibility.
• Organizations, teams, roles, and permissions pass access tests.
• OAuth, SSO, MFA, callbacks, cookies, and logout pass.
• Delta replay and rollback routing are tested.
• Better Auth secrets, sessions, and compatibility code are removed after soak.

Related

• Users
• Organizations
• Permissions
• Sessions & tokens
• Testing