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 it's users.

Basic Export / Import

With Basic Export / Import, you are simply taking an export from your previous tool and importing them into Clerk. The most common way to handle this is by making use of the Backend API and it's CreateUser API endpoint. It's important to noote that the CreateUser endpoint has a rate limit of 20 requests per 10 seconds.

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 user's 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; meaning there becomes some 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. Again you'll have to consider our API's rate-limiting against when evaluating this option.

Active Sessions / Session Management

Another consideration is how centered aroud how you handle session management. While most Auth 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 which system handles your user's active sessions and will likely end any currently active sessions initiated by your previous 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 into Clerk, you may want to be able to still reference that previous ID alongside of 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 and 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 by heading into Clerk Dashboard, going to Sessions -> Edit and adding the following:

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

Trickle migration

With 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 Trickle migration, you're 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.

It's important to note here that Clerk only charges by Monthly Active Users and never based on your total number of Users in the user table – so during this period you'll only be charged for user's who create an active session within Clerk. Head to our pricing page to get the full details on how Clerk charges.

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 time-window should guide your decision here.

Dealing with the delta

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

clerk/migration-script

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

Migration Guides

Clerk is hard at work writing up more and more specific migration guides and tools. If you have are interested in specific guides please provide more feedback at https://feedback.clerk.com