Migrate from Clerk

Learn how to migrate users and organizations from Clerk.

Introduction

Migrate your existing user data from Clerk into WorkOS using the AuthKit API. Follow these steps to export and then import your users.

1. Export Clerk user data

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

Export passwords

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 use the Clerk backend API to export them with your user data as a CSV file.

Clerk does not make the plaintext passwords available for export.

2. Import users into WorkOS

After obtaining the necessary export files, choose one of two options for importing your user data into WorkOS.

A. Using the WorkOS import tool

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.

B. Using WorkOS APIs

Use the data from the Clerk API or from a JSON file received from their support team to create users via the WorkOS API. Note that user creation is rate-limited. See the rate limits documentation for more information.

Map the default fields from the Clerk export to WorkOS Create User API parameters:

Clerk		WorkOS API
`email_addresses`	→	`email`
`first_name`	→	`first_name`
`last_name`	→	`last_name`

Handle users with multiple email addresses

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.

Import passwords

Import passwords during the user creation process, or later using the WorkOS Update User API.

Clerk uses the bcrypt password hashing algorithm, which WorkOS supports. Pass the following parameters to the WorkOS API:

The password_hash_type set to 'bcrypt'
The password_hash set to the password_digest field from your Clerk export

Users who previously signed in through Clerk using social auth providers, such as Google or Microsoft, can continue to sign in with those providers after migrating to WorkOS.

Configure the relevant provider’s client credentials in WorkOS. See the integrations page for guidance.

After configuring the provider, users sign in with their provider credentials and are automatically linked to a WorkOS user. WorkOS uses the email address from the social auth provider to determine this match.

3. Create organizations

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

Creating Organizations

Export your Clerk organizations using the Clerk Backend SDK to programmatically paginate through each organization. Then use the WorkOS API to create matching organizations.

Adding user memberships

Export Clerk organization memberships using Clerk’s Backend SDK. Then use the WorkOS Organization Membership API to add each user to their respective organization.

4. Multi-Factor Auth

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.

Next steps

With your users imported, start using WorkOS to manage authentication. See the Quick Start guide to learn how to integrate WorkOS AuthKit into your application.