Migrate to Clerk from another platform
There are typically two main strategies for migrating your existing user management from a different platform into Clerk:
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 are 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 Backend API and its CreateUser API endpoint. It's important to note that the CreateUser endpoint is rate limited. Please review our Rate Limits(opens in a new tab) page for details.
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.
Note: If you are expecting to import 100k+ users, we recommend reaching out to support@clerk.dev where we can coordinate increases to the rate limits and ensure a seamless import of your data.
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(opens in a new tab). 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.
It's important to note 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 users 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 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 Clerk's backend API. The script respects Clerk's backend rate limits(opens in a new tab) and gracefully handles errors. We suggest you customize the Zod schema(opens in a new tab) to your application's needs.
To use Clerk's migration script, clone the repository(opens in a new tab) and follow the instructions in the README.
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(opens in a new tab)
Last updated on April 8, 2024