Skip to main content

The Clerk CLI exports your users from Auth0's Management API with clerk migrate export auth0, then creates them in Clerk with clerk migrate import.

Two Auth0 limits affect this migration:

  • Password hashes: The Management API doesn't return them. Auth0 releases them only through a support request. Without them, your users arrive with no password and have to reset.
  • Tenants over 1,000 users: The users endpoint stops paging at 1,000. Past that, Auth0's bulk user export job is the only way to get the rest.

Migrate with an AI agent

If you work with an AI coding agent, the clerk-migrate skill can run your migration for you with the Clerk CLI. Install Clerk's skills:

terminal
npx skills add clerk/skills

Then ask your agent to migrate your users to Clerk. The skill exports your users, runs a dry run against your instance, and shows you what it found. It imports only after you approve.

What you need

Install the Clerk CLI, sign in, and link the project directory you'll run the migration from to the Clerk application you're importing into:

terminal
npm install -g clerk
clerk auth login
clerk link

To skip clerk auth login and clerk link, set CLERK_SECRET_KEY to the of the instance you're importing into, or pass it with --secret-key.

To skip the global install, replace clerk with npx clerk@latest in each command. To update an existing install, run clerk update.

import and undo target the linked application's development instance by default. Pass --instance prod or a full instance ID to choose another. With a Secret Key, the key picks the instance, so pass the production instance's key to import into production. For other ways to pick the instance and Secret Key, see choose the destination instance.

The CLI stores each run in .clerk/migrate/<run_id>/ and adds .clerk/ to .gitignore. To store runs elsewhere, see command behavior.

Warning

New development instances have a limit of 100 users. Production instances have no user limit. Before creating users, the import checks a development instance's count against its limit and rejects the users past it. To rehearse with a larger export, import into development with --allow-partial, check the result, undo the run, then import everyone into production. See instance user limits for the commands, overrides, and fallback behavior.

An Auth0 machine-to-machine application

The export authenticates as an application, not as your own Auth0 account.

  1. In the Auth0 dashboard, navigate to Applications, open APIs, select Auth0 Management API, and select the Machine to Machine Applications tab.
  2. Authorize an application (create one if you don't have a suitable one) and grant it the read:users scope.
  3. Copy the application's Domain, Client ID, and Client Secret. Use the tenant's *.auth0.com domain, not a custom domain. The Management API only answers on the tenant domain.

What migrates

  • Passwords, if you obtain hashes from Auth0: The import uses each passwordHash you add to the export as bcrypt. Without one, the user has no password.
  • Auth0 IDs: user_id is a provider|id string such as auth0|abc123 or github|12345, and the import copies it unchanged into the Clerk user's external_id. To keep referencing it in your app, see foreign keys.
  • Unverified emails and phones: They stay unverified by default. email_verified and phone_verified decide where an address lands, and a missing value counts as unverified. The import keeps an address Auth0 never confirmed off the primary fields and attaches it as unverified. The checks reject a user whose only email is unverified when your instance requires an email. To reserve those unverified addresses instead, see unverified emails and phones.
  • Names: given_name and family_name take priority and become the first and last name. If either is present, the source ignores name. Without them, it splits name, unless it's the user's own email address, which Auth0 writes there for database users.
  • Blocked users: The import bans a user with blocked: true.
  • Metadata: user_metadata, which your users could edit in Auth0, becomes Clerk's unsafeMetadata, which they can still edit. app_metadata becomes privateMetadata, which is server-side only.
  • Signup dates: The import keeps the date from Auth0's created_at.

What doesn't migrate

  • Social accounts: Enable the same providers on the SSO connections page in the Clerk Dashboard. When a user signs in with one, Clerk links it to their imported account by verified email address. Clerk doesn't link to an address the import attached as unverified, so that sign-in creates a separate user. To link those users, import with --reserve-unverified. If you reserve the address and the provider doesn't confirm it, Clerk asks the user to verify it before linking. See account linking.
  • Multi-factor authentication (MFA) enrollments: Auth0 doesn't export them, so users enroll again in Clerk.
  • Identities, session counts, and tenant internals: The import omits these fields. They have no Clerk equivalent.

Export your users from Auth0

Run the export with your application's domain and client ID. The CLI reads the client secret from AUTH0_CLIENT_SECRET, or prompts for it:

terminal
clerk migrate export auth0 --domain <auth0_tenant_domain> --client-id <client_id>

The domain works with or without a scheme, so both my-tenant.us.auth0.com and https://my-tenant.us.auth0.com/ are accepted. Leave the credentials off and the CLI reads AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_CLIENT_SECRET, then prompts for them. The prompt masks the secret, and a value entered at a prompt stays out of your shell history. If Auth0 rejects the credentials, or issues a token without read:users, an interactive run asks for all three again. With --yes, --json, in an agent run, or without a terminal, the export doesn't prompt. It fails and names the missing values.

The export saves your users as export.json in a new run, and prints the run ID and a field coverage table:

Field coverage
  ✓ 412/412 have an email address
  ✗ 0/412 have a phone number
  ! 96/412 have a username
  ! 300/412 have a first name
  ! 288/412 have a last name

Pass -o <path> to write the file somewhere else. The path has to end in .json.

If your tenant has more than 1,000 users

The export stops at Auth0's ceiling and says so, naming the total your tenant reports:

Auth0 only pages through the first 1000 users on this endpoint, and this tenant
reports 4318. Exported what is reachable; use Auth0's bulk user export job for
the rest.

Auth0 can also report a larger tenant's total as 1,000. Then the warning says the endpoint "counts no higher, so there may be more" instead of naming a total. If Auth0 returns fewer users than it reported, the export warns about that too.

The export still writes the users it got, but exits with code 1, and --json output includes truncated: true, so a script can tell.

Run Auth0's bulk user export job for the full tenant. Auth0 delivers it gzip-compressed, so decompress it, then import that file with clerk migrate import <path> --source auth0 instead of the CLI's own export. A file Auth0 wrote doesn't name its source, so it needs --source.

Get the password hashes

Auth0's Management API returns no password_hash field at any tier, so the export can't include one, and warns whenever it exports users. To keep your users' passwords:

  1. Open a support request with Auth0 asking for a password hash export for your tenant.

  2. Add the digest to each user in the run's export.json as a passwordHash field. By default, the path is .clerk/migrate/<export_run_id>/export.json.

  3. Use the edited file's path instead of <export_run_id> when you import. Importing by run ID rejects a file changed after export. The file still names its source, so it needs no --source:

    terminal
    clerk migrate import .clerk/migrate/<export_run_id>/export.json --dry-run

    Auth0's digests are bcrypt, which is what the auth0 source assumes. The checks reject a user whose passwordHash isn't a well-formed bcrypt digest.

If you skip this, those users arrive without a password and sign in through a reset or an enabled social connection.

Import your users into Clerk

Check the export against your Clerk instance first. A dry run writes nothing and skips the import's consent, legal acceptance, and reservation questions, so add --skip-legal-checks to preview importing users without legal acceptance, or --reserve-unverified to preview reserving unverified emails and phones:

terminal
clerk migrate import <export_run_id> --dry-run

The export recorded its source, so the import needs no --source. If the checks reject a user, fix the file or instance, or pass --allow-partial to import the users that pass. See check before you import.

After the checks pass, rerun the same command with --yes instead of --dry-run, keeping the input and other flags. Leave off --yes to confirm at a prompt.

Use the import run's ID to check its results or undo it. To continue an interrupted import, run the same command again.

Verify the migration

  1. Read what the run did. It lists the users that failed or were skipped, and why:

    terminal
    clerk migrate runs <import_run_id>
  2. Confirm the users exist in Clerk:

    terminal
    clerk users list
  3. Compare the created count from clerk migrate runs against your tenant's total in Auth0. If exactly 1,000 users came across and your tenant has more, you hit the pagination ceiling.

Undo the migration

Preview the users the import created, using the import run's ID:

terminal
clerk migrate undo <import_run_id> --dry-run

Then delete them:

terminal
clerk migrate undo <import_run_id> --yes

--yes doesn't delete users who have signed in since the import. Add --include-signed-in to authorize those deletions too. Confirming at the interactive prompt also authorizes them.

Pass the same --instance, --app, or --secret-key you gave the import. See undo an import for confirmation rules, refusal conditions, and retries.

Next steps

Foreign keys

Keep referencing your users by the IDs they had before the migration.

How the CLI migrates users

Learn how the CLI checks users, continues an interrupted import, and undoes one.

Account linking

Learn how Clerk links a social sign-in to an imported user.

Feedback

What did you think of this content?

Last updated on