# Migrate from Auth0

The [Clerk CLI](https://clerk.com/docs/cli.md) 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](#get-the-password-hashes). 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](#if-your-tenant-has-more-than-1-000-users) 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](https://clerk.com/docs/guides/ai/skills.md) can run your migration for you with the Clerk CLI. Install Clerk's skills:

filename: terminal
```sh
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](https://clerk.com/docs/cli.md), sign in, and link the project directory you'll run the migration from to the Clerk application you're importing into:

filename: terminal
```sh
npm install -g clerk
clerk auth login
clerk link
```

To skip `clerk auth login` and `clerk link`, set `CLERK_SECRET_KEY` to the Secret Key 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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#command-behavior).

> New development instances have a [limit of 100 users](https://clerk.com/docs/guides/development/managing-environments.md). 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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#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](https://manage.auth0.com), 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](https://clerk.com/docs/guides/development/migrating/plan-your-migration.md#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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#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**](https://dashboard.clerk.com/~/user-authentication/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](https://clerk.com/docs/guides/configure/auth-strategies/social-connections/account-linking.md).
- **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.

1. ## 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:

   filename: terminal

   ```sh
   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:

   ```text
   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`.
2. ### 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:

   ```text
   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](https://auth0.com/docs/manage-users/user-migration/bulk-user-exports) 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`.
3. ### 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`:

      filename: terminal

      ```sh
      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](https://clerk.com/docs/guides/configure/auth-strategies/social-connections/overview.md).
4. ## 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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#legal-acceptance), or `--reserve-unverified` to preview reserving [unverified emails and phones](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#unverified-emails-and-phones):

   filename: terminal

   ```sh
   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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#continue-an-interrupted-import), run the same command again.
5. ## Verify the migration

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

      filename: terminal

      ```sh
      clerk migrate runs <import_run_id>
      ```

   2. Confirm the users exist in Clerk:

      filename: terminal

      ```sh
      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:

filename: terminal
```sh
clerk migrate undo <import_run_id> --dry-run
```

Then delete them:

filename: terminal
```sh
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](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md#undo-an-import) for confirmation rules, refusal conditions, and retries.

## Next steps

- [Foreign keys](https://clerk.com/docs/guides/development/migrating/plan-your-migration.md#foreign-keys): Keep referencing your users by the IDs they had before the migration.
- [How the CLI migrates users](https://clerk.com/docs/guides/development/migrating/how-the-cli-migrates-users.md): Learn how the CLI checks users, continues an interrupted import, and undoes one.
- [Account linking](https://clerk.com/docs/guides/configure/auth-strategies/social-connections/account-linking.md): Learn how Clerk links a social sign-in to an imported user.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)
