Account Migration
To following guide will show you how to move your users from your current authentication solution to SuperTokens
Overview
The process of migrating your accounts can be broken down into two parts:
Creating new users on the fly
In order to ensure a smooth migration process, with no downtime, you need to be able to directly create new users from the legacy sign up flow. This is necessary since there will be a time gap between when you export all your data for bulk import and when you go live with SuperTokens.
New users might get created in that interval through your legacy authentication provider. Hence, you will also need to create them in SuperTokens to keep the data in sync.
Adding most of your users through a bulk import
After you have set in place the lazy migration process you can move on to adding most of your users. This will happened through the bulk import API. The process is asynchronous and can work with large amounts of data.
Before You Start
This guide assumes that you have already integrated SuperTokens with your existing stack. If you have not, please check the Quickstart Guide and explore all the supported authentication methods.
Steps
1. Update the legacy sign up flow
Modify the legacy sign up flow logic to also create new users in SuperTokens.
This can be done through the Import User endpoint that allows you to directly create accounts.
Call the endpoint from the authentication flow used by your legacy provider.
After you have added the new sign up logic you can deploy the changes and move to the next step.
If your application does not have a sign up process or if new users are created manually you can skip this step
curl --location --request POST '<CORE_API_ENDPOINT>/bulk-import/import' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json; charset=utf-8' \
--data '
{
"externalUserId": "user_12345",
"userMetadata": {
"firstName": "Jane",
"lastName": "Doe",
"department": "Engineering"
},
"userRoles": [{ "role": "admin", "tenantIds": [] }],
"totpDevices": [
{
"secretKey": "JBSWY3DPEHPK3PXP",
"period": 30,
"skew": 1,
"deviceName": "Main Device"
}
],
"loginMethods": [
{
"isVerified": true,
"isPrimary": true,
"timeJoinedInMSSinceEpoch": 1672531199000,
"recipeId": "emailpassword",
"email": "[email protected]",
"passwordHash": "$2b$12$KIXQeFz...",
"hashingAlgorithm": "bcrypt"
}
]
}
'
If your current authentication logic includes a password change flow, you will also have to update it, to keep the user data in sync.
2. Export the accounts from your legacy provider
Export the users from your legacy authentication provider and adjust the data to match the request body schema used in the Add Users for Bulk Import endpoint.
3. Perform the bulk migration process
If your application has a sign up process please make sure that you have completed the first step. Otherwise, new accounts that get created after you have exported your users will not be available in SuperTokens.
3.1 Add the accounts that should be imported
Using the data that you have generated in the previous step, call the Add Users for Bulk Import endpoint.
This step stages the data that will be imported later on by the background job.
Keep in mind that the endpoint has a limit of 10000 users per request.
curl --location --request POST '<CORE_API_ENDPOINT>/bulk-import/add-users' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
users: [
{
"externalUserId": "user_2",
"userMetadata": {
"firstName": "John",
"lastName": "Doe",
"department": "Marketing"
},
"userRoles": [{ "role": "editor", "tenantIds": [] }],
"loginMethods": [
{
"isVerified": true,
"isPrimary": true,
"timeJoinedInMSSinceEpoch": 1672617599000,
"recipeId": "thirdparty",
"email": "[email protected]",
"thirdPartyId": "google",
"thirdPartyUserId": "google_987654321"
}
]
}
]
}
Every 5 minutes the SuperTokens core service will run a cron job that goes through the staged users and tries to import them. If a user gets imported successfully it will get removed from the staged list.
3.2 Monitor the progress of the job
In order to determine if all the users have been processed by the import flow call the Count Staged Users API.
Before doing that, let's first understand the different states in which a staged user can be. During the import process, the user can have one of the following statuses:
- NEW: The user has not yet been picked up by the import process.
- PROCESSING: The import process has selected the user for import.
- FAILED: The import process has failed for that user.
If a user gets imported successfully it will then be removed from the staged list. Hence, no status is needed for that state.
With this new information let's get back to the count users endpoint.
The request counts the users that are staged for import.
Pass a status filter as a query parameter (e.g. status=NEW) to count only the users with that status.
Given that information, to check if your import is finalized do the following:
- Call the
count usersAPI once without any filters. If the count is 0, then the import process is done. - If the count is not 0, then check if you still have rows that are getting processed (
status=PROCESSING) or if there are rows that have not yet been picked up by the import job (status=NEW) - If the only rows that are left are the ones with the
FAILEDstatus, then proceed to step3.3. There you will see how to debug those issues.
curl --location --request GET '<CORE_API_ENDPOINT>/bulk-import/users/count?status=PROCESSING' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json; charset=utf-8' \
3.3 Handle staged users that failed to import
Go through this step only if you have staged users that failed to import. This can happen for a number of reasons. Some of the most common ones:
Email/phoneNumberalready existsexternalUserIdis being already used by other user- A primary user already exists for the email but with a different login method
If at the end of the previous step you have determined that you have staged users that failed to import debug the issues with the get users API.
curl --location --request GET '<CORE_API_ENDPOINT>/bulk-import/users?status=FAILED' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json; charset=utf-8' \
The response will include the import error messages for each specific user.
Use them to determine what needs to be corrected in your import data.
After you have fixed the issues, run the process again, from step 3.1, only for the corrected data.
If you all your data has been imported then you can now consider the account migration process as done. Go on to the session migration step to complete the entire migration flow.