Migrate from Clerk

Move Clerk users, organizations, memberships, and application sessions to Authdog without changing downstream records keyed on Clerk IDs. This guide covers export, identity mapping, password choices, staged cutover, rollback, and validation.

Prerequisites

• An Authdog tenant, project, and environment for a staging rehearsal.
• Clerk Backend API access to read users, organizations, memberships, invitations, and configuration.
• An inventory of every Clerk frontend/backend SDK, middleware check, webhook, JWT template, and application URL.
• Cutover cohorts, rollback thresholds, and an owner for data reconciliation.

Migration shape

1. Inventory and export — capture users, identities, organizations, roles, and custom claims.
2. Map and import — preserve stable Clerk IDs and recreate access in Authdog.
3. Parallel run — move controlled cohorts while Clerk remains recoverable.
4. Cut over and retire — switch all clients, soak, and revoke Clerk credentials.

1. Inventory Clerk

Record sign-in identifiers, MFA/passkey use, allowed origins, redirect URLs, session lifetime, impersonation/admin flows, and whether metadata is public, private, or unsafe.

2. Export users and organizations

Use Clerk's Backend API with pagination. Retain:

• Clerk user id as source external identifier
• All email addresses and phone numbers, including primary and verification state
• Name, image, username, and required metadata
• External accounts and provider identifiers
• Account lock/banned/deleted state where applicable
• Organization id, name, slug, metadata, memberships, and roles
• Creation and last-sign-in timestamps for cohort planning

Store Clerk user id as the Authdog external identifier and keep clerk_org_id → Authdog organization ID mappings. Emails, usernames, and slugs can change; do not use them as durable joins.

Password strategy

Password digest availability and accepted algorithms depend on export capabilities and target support:

• Compatible hash import — use only when Clerk supplies digest plus required parameters and Authdog confirms that exact format is supported.
• Progressive migration — verify the user's password against Clerk once through a server-side bridge, then establish the Authdog credential.
• Reset or passwordless — use reset, magic link, social, or enterprise SSO when hashes are unavailable.

Do not infer compatibility from an algorithm label alone; variant, cost, salt, and encoding matter. Passkeys, TOTP secrets, backup codes, and active sessions should be treated as non-portable unless both systems explicitly support transfer. Never collect raw passwords in logs or migration files.

3. Map organizations, roles, and identities

Create Authdog organizations before memberships. Map Clerk organization roles and permissions to Authdog roles and permissions; distinguish organization-scoped access from application-wide roles. Preserve unmapped metadata only when an application still needs it.

Recreate OAuth and enterprise connections with Authdog redirect URLs. Authdog links identities by verified email, so test users with multiple verified addresses, external accounts sharing one address, and unverified identifiers. Decide which email becomes primary before import.

Translate Clerk JWT template claims deliberately. Prefer first-class organization membership and roles over copying authorization JSON into every session. See Authorization.

4. Import and update applications

Import through console tooling or the REST Directory API:

1. Upsert user profile and verification state.
2. Set Clerk user id as external identifier.
3. Attach required metadata and suspend blocked users.
4. Create organization memberships and mapped roles.
5. Link supported provider identities and record credential migration state.

Replace Clerk components/hooks and backend middleware with Authdog components or SDKs (quickstarts). Configure the Authdog environment public key (pk_...), update callback/logout URLs, and validate Authdog sessions on backends. Rewrite code depending on Clerk userId, orgId, orgRole, JWT templates, or webhook payloads. See Backend requests and Sessions & tokens.

5. Stage cutover and rollback

1. Rehearse import and representative sign-in paths in staging.
2. Run an initial export, then reconcile users and memberships changed before cutover.
3. Move employees, then a small organization or application cohort.
4. Keep dual-issuer validation temporary, explicit, and measured.
5. Monitor duplicate accounts, login failures, org selection, webhook delivery, and access denials.
6. After soak, disable Clerk sign-ups and callbacks, rotate secrets, and remove Clerk middleware.

Rollback: route affected cohorts back to Clerk while preserving Clerk IDs and source membership snapshots. Define one authority for profile and organization writes during parallel run to prevent drift.

Validation checklist

• User, organization, and membership counts reconcile.
• Every Clerk user id and organization mapping is retained.
• Password strategy works without assumed digest compatibility.
• Primary emails, verification, external accounts, and disabled states match.
• Organization roles and permissions pass representative access tests.
• OAuth, SSO, MFA, callbacks, and logout paths pass.
• Backends and webhooks consume Authdog identity/session shapes.
• Delta changes and rollback routing are tested.
• Clerk keys and dual-issuer code are removed after soak.

Related

• Users
• Organizations
• Roles & permissions
• Quickstarts
• Integrations