Migrate from Clerk

The WorkOS User Management API allows you to migrate your existing user data from a variety of existing sources. In this guide, we will walk through the steps to export, and then import your users from Clerk.

Clerk allows for exporting user data directly from their API using their Backend SDK.

If your Clerk users currently sign in using password-based authentication, and you’d like to import those passwords into WorkOS, then you’ll need to contact Clerk support.

After opening a ticket with Clerk, it can take up to a week or more for your request to be processed. At the end you’ll be given a JSON file that includes user data and hashed passwords.

Once you’ve obtained the necessary export files, you have two options for importing your user data into WorkOS.

WorkOS has a public GitHub repository containing code that can be run to import users into WorkOS using the data retrieved from Clerk support in the previous step.

If you’d rather write your own code, or if you chose to not export data via Clerk support, the same process can be completed using the public WorkOS APIs, as described below.

Using the data either from the Clerk API or from a JSON file received from their support team, you can use the WorkOS API to create users during the import. Keep in mind that user creation is rate-limited. You can view the docs on the rate limits for more information.

Using the default fields from the Clerk export, use the following mapping from Clerk to parameters in your WorkOS Create User API calls:

In the case of a user with multiple email addresses, Clerk separates them with a pipe symbol:

"email_addresses": "john@example.com|john.doe@example.com",

Unfortunately there’s no way to know which email is the primary one from the export alone. Clerk does expose this information by retrieving the User object from their API.

If you also exported passwords from Clerk, you can import them during the user creation process, or later using the WorkOS Update User API.

Clerk uses the bcrypt password hashing algorithm, which is supported by WorkOS. Make sure to pass the following parameters to the WorkOS API:

If you have users who previously signed in through Clerk using social auth providers, such as Google or Microsoft, those users can continue to sign in with those providers after you’ve migrated to WorkOS.

Check out our integrations page for guidance on configuring the relevant provider’s client credentials in WorkOS.

After your provider is configured in WorkOS, users can sign in with their provider credentials and will be automatically linked to a WorkOS user. WorkOS uses the email address from the social auth provider to determine this match.

Clerk’s organizations are analogous to WorkOS organizations – both represent a B2B customer.

If you’d like to export your Clerk organizations, you can use the Clerk Backend SDK to programmatically paginate through each organization. You can then use the WorkOS API to create matching organizations.

You can export Clerk organization memberships using Clerk’s Backend SDK, and then use the WorkOS Organization Membership API to add each user to their respective organization.

There are some differences between the MFA strategies offered by Clerk and WorkOS.

Clerk supports SMS-based second factors, however WorkOS does not due to known security issues with SMS. Users who have SMS-based second factors will need to switch to using email-based Magic Auth, or re-enroll in MFA using a TOTP-based authenticator instead. See the MFA guide for more information on enrolling users.

After the import, you can now start using WorkOS to manage your users. If you haven’t, take a look at the Quick Start guide to learn how to integrate WorkOS User Management into your application.