# Migrate from WorkOS

The [Clerk CLI](https://clerk.com/docs/cli.md) exports your users from the WorkOS User Management API with `clerk migrate export workos`, then creates them in Clerk with `clerk migrate import`.

WorkOS doesn't export password hashes and returns time-based one-time password (TOTP) secrets only at enrollment. Users who signed in with a password must reset it in Clerk or use single sign-on (SSO) or a social connection.

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

### A WorkOS API key

The export authenticates with your WorkOS secret API key, the one starting with `sk_`.

1. In the [WorkOS dashboard](https://dashboard.workos.com), switch to the environment whose users you're migrating.
2. Navigate to **API Keys** and copy the secret key.

WorkOS is API-only, so there's no database connection to set up. If your app mirrors WorkOS users into its own database through webhooks, that copy holds no credentials either. The export reads from the User Management API directly.

## What migrates

- **Unverified emails:** They stay unverified by default. WorkOS's `email_verified` decides where an address lands. Clerk creates primary identifiers as verified, so the import keeps an address WorkOS 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:** `first_name` and `last_name` become the Clerk user's first and last name.
- **Metadata:** WorkOS `metadata` becomes `privateMetadata`, which only your backend can read or write. If your app exposed metadata keys through a WorkOS JWT template, move those keys to `publicMetadata` after the import.
- **Signup dates:** The import keeps the date from WorkOS's `created_at`.
- **WorkOS IDs:** Each user's `id` (a `user_…` string) becomes the Clerk user's `external_id`, which is how a re-run recognizes the users it already created. To keep referencing it in your app, see [foreign keys](https://clerk.com/docs/guides/development/migrating/plan-your-migration.md#foreign-keys).
- **Your own WorkOS `external_id`:** If you set an `external_id` on WorkOS users, the import stores it as `workosExternalId` in that same `privateMetadata`, because the Clerk `external_id` holds the WorkOS user ID.

## What doesn't migrate

- **Passwords and TOTP secrets:** Plan how you'll tell users about the password reset before you switch over.
- **Organizations, SSO connections, sessions, and profile pictures:** The import omits these. WorkOS has no phone numbers or usernames on users, so there's nothing to import for those.

1. ## Export your users from WorkOS

   Run the export, and enter your WorkOS secret key when the CLI asks:

   filename: terminal

   ```sh
   clerk migrate export workos
   ```

   Without `--api-key`, the CLI reads `WORKOS_API_KEY`, then prompts for it. The prompt masks what you type, and a value entered at a prompt stays out of your shell history. If WorkOS rejects the key, an interactive run asks again. With `--yes`, `--json`, in an agent run, or without a terminal, the export doesn't prompt, and fails if the key is missing or rejected.

   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
     ! 300/412 have a first name
     ! 288/412 have a last name
     ! 57/412 have metadata
     ✗ 0/412 have a password (WorkOS returns none)
   ```

   Pass `-o <path>` to write the file somewhere else. The path has to end in `.json`.
2. ### Record which OAuth providers your users have

   To see which social providers your users sign in with, add `--with-identities`:

   filename: terminal

   ```sh
   clerk migrate export workos --with-identities
   ```

   The export omits identities by default. WorkOS has no bulk identities endpoint, so `--with-identities` adds one request per user. For 1,000 users, that's about 1,010 requests instead of 10.

   In a terminal, the export asks whether you want identities once it knows how many users there are. The default answer is no. Pass `--no-with-identities` to skip the question. With `--yes`, `--json`, in an agent run, or without a terminal, the export doesn't ask, and skips identities unless you pass `--with-identities`.

   With identities, the export adds an **OAuth providers** block under the coverage table, and keeps an `identities` array on each user who has at least one provider:

   ```text
   OAuth providers
     GoogleOAuth        2 users
     MicrosoftOAuth     1 user
     no OAuth provider  2 users
     not readable       1 user
     Those users have no `identities` field in the export, rather than an empty one.
   ```

   A user with two providers is counted under both, so the counts can add up to more than your user count. `not readable` means the lookup for that user failed, so their providers are unknown. If WorkOS rejects the key partway through, the whole export stops instead.

   Clerk can't import identities: the endpoint that creates users has no field for social accounts. Use the breakdown to decide which [social connections](https://clerk.com/docs/guides/configure/auth-strategies/social-connections/overview.md) to enable in Clerk before you import. 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).
3. ## Import your users into Clerk

   Your WorkOS users have no password to bring. If your Clerk instance requires one, the checks warn that these users will be created without a password and have to sign in another way, such as a code or a social connection. They also print the `clerk config patch` command that makes password optional. If password is your instance's only sign-in method, the checks reject these users instead: enable a code, link, social, or SSO sign-in method first.

   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.
4. ## 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. Sign in as a migrated user through a password reset or an enabled SSO or social connection. If you use a password reset, confirm the email reaches the imported address.

## 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)
