# Auth0 to Clerk: export and import migration

## The order

1. Export users from the Auth0 Management API (paginated user list). This
   export is a snapshot in time, so plan the export and import as close
   together as possible, or schedule a maintenance window.
2. Transform each user: set external_id to the Auth0 user_id, map email and
   email_verified into email_addresses, carry name, picture, and any app
   metadata into public_metadata.
3. Import with Clerk's CreateUser backend endpoint, declaring your
   password_hasher value (the algorithm Auth0 used for the digest). Clerk
   transparently upgrades hashes to the more secure bcrypt on first login.
4. The CreateUser endpoint is rate limited. Use Clerk's open-source
   migration tool (takes JSON or CSV, respects backend rate limits, handles
   errors gracefully) rather than hand-rolled parallel loops that hit 429s.
5. Test the whole thing against a development instance first. Set the dev
   import flag in the migration tool env to allow importing into a dev
   instance.

## What changes at cutover

- Sessions end. Clerk becomes the session manager, so active sessions from
  Auth0 do not survive the switch. Warn users or force a re-login window.
- Keep the external_id breadcrumb. Your old ids live on as external_id so
  audit trails and old foreign keys still resolve.
- Export/import cannot migrate users created after the snapshot. For the
  tail, either re-run the import for deltas or pair this with a trickle
  migration that converts users at login.

## Checklist

- Verify a migrated user can sign in with their old password on the first
  try. That proves the password_hasher declaration was right.
- Verify email_verified survived the import, or users get asked to verify
  an address they already verified years ago.
- Count users in Auth0 vs users in Clerk after import. The diff is your
  follow-up list.