Migrate to Clerk from another platform

There are typically two main strategies for migrating your existing user management from a different platform into Clerk:

• Basic Export / Import
• Trickle migration

Each of these have trade-offs you'll need to consider on behalf of for your application and its users.

Basic export / import

With basic export / import, you're taking an export from your previous tool and importing data into Clerk. The most common way to handle this is by making use of the CreateUser Backend API endpoint. It's important to note that the CreateUser endpoint is rate limited. For more information, see the guide on rate limits.

You'll also need to provide your password_hasher value (The hashing algorithm used to generate the password digest) and in some instances Clerk will transparently upgrade your users' password hashes to the more secure Bcrypt hashing algorithm. More details on this topic are available in the Create a new user Backend API Reference docs.

Considerations

When evaluating the Basic Import / Export workflow there are a few tradeoffs you'll need to consider.

Data consistency

Consider that any export of your data will be a snapshot in time. This means that there is a potential of your data being out of sync at the time of import. To work around this you might script and coordinate the export and import actions to be as close in time as possible, or you might schedule some kind of downtime or maintenance window to complete this action. Be sure to consider Clerk API rate-limits when evaluating a potentially time-sensitive migration approach.

Active sessions / session management

Another consideration is centered around how you handle session management. While most authentication providers don't provide session management out-of-the-box, Clerk does. This means that when you switch over to using Clerk you'll be changing the system that handles your users' active sessions. This will likely end any currently active sessions initiated by your previous session management service (unless you are able to gracefully handle this somehow within your architecture).

Foreign keys

In your previous system you likely had some kind of ID / Foreign Key that you were using. As you migrate data into Clerk, you may want to continue referencing that previous ID alongside Clerk's provided user IDs. While each use case might have some variation, a common strategy is to store previous IDs as an external_id. You can then use Clerk's JWT customization to enrich a userId value with the external_id when present, or fallback to using Clerk's native ID when dealing with new users who don't have an external_id from your legacy system. You can configure this in the Clerk Dashboard Sessions page. Under Customize session token, click Edit and add the following:

{
  "userId": "{{user.external_id || user.id}}"
}

Trickle migration

With a trickle migration you are slowly migrating your users from your previous system into Clerk. Depending on your application's needs this can be a great way to accomplish migration in a gradual and more controlled way. With a trickle migration, you are keeping both systems running for some period of time, handling the transition between systems opaquely to your users, and then eventually cutting over fully to Clerk as your user and session management system or record. By handling this transition gradually you'll maintain more control and put less pressure on a single coordinated event.

Considerations

As with the Basic Import / Export workflow there are a tradeoffs you'll need to consider, to determine which strategy is best for your application.

The cost and overhead of running two systems in parallel

Because you'll need both systems available when doing a gradual migration, there is naturally additional short-term costs related to having both running systems at the same time.

Determining the appropriate length of time

As part of the trickle migration, you'll need to determine an appropriate length of time for the migration to take place. For some applications this might be a few weeks, but for others it might be more appropriate to run this for months. Your hard-costs, coordination costs, underlying complexity, and the amount of active users you expect in your migration time-window should guide your decision here.

Dealing with the delta

A trickle migration is great for upgrading active users and sessions to take advantage of Clerk but there will always be some users who won't create an active session within the migration window and therefore will need to be migrated by other means, typically via Basic Import / Export. However, the benefit of a trickle migration is that the risk of coordination becomes much lower as the delta users are likely to be less active, are less in numbers, and therefore the risk of data de-synchronization is reduced.

Migration tools

To aid in basic migrations, Clerk provides an open-source script that takes a JSON file as input, containing a list of users, and creates a user in Clerk using the Backend API. The script respects the backend rate limits and gracefully handles errors. We suggest you customize the Zod schema to your application's needs.

To use Clerk's migration script, clone the repository and follow the instructions in the README.

Migration guides

Clerk is hard at work writing up more specific migration guides and tools. If you're interested in specific guides, contact us at https://feedback.clerk.com