Migrate from other services
Learn how to export and import users from your own data store.
The WorkOS User Management API allows you to migrate your existing user data from a variety of sources. In this guide, we’ll walk through the steps to export, and then import users from your own data store.
While moving authentication related metadata to WorkOS, most applications will continue to store certain user information in their data store. This common subset of data will usually be the following:
While preparing the migration, you’ll want to ensure this information is programmatically available for use in the import step, this can mean:
- Exporting the relevant data to a file such as JSON or CSV.
- Allowing the data to be queried from the data store directly.
After the data is accessible, we can configure the import.
For each of your users, you can call the WorkOS Create User API. This will create a matching User object within WorkOS.
A successful response will include a new WorkOS user ID, most apps will want to persist this WorkOS user ID alongside the application-local user object.
Email addresses are unique to each WorkOS environment. If you have a subset of users already in WorkOS, you may need to handle constraint violation errors.
There are now several options on how to proceed, depending on your application’s needs:
If your users currently use password-based authentication, you can import existing password hashes during the users creation process, or later using the WorkOS Update User API.
WorkOS currently supports passwords hashed using the bcrypt, firebase-scrypt, and ssha algorithms. For firebase-scrypt passwords, see the Firebase Migration guide for an example of how to format the password_hash. For ssha passwords, they must be formatted as {SSHA}<base64(sha1 digest + salt)>.
Once imported, users can continue to sign-in with their existing password, without having to go through a password reset flow.
If you are unable to export passwords from your existing data store, whether for security reasons or other limitations, you can programmatically trigger a password reset flow using the WorkOS Password Reset API.
This process can be initiated at any time, and doesn’t need to happen during the user import process.
Some applications may want to remove password-based authentication when switching to WorkOS, in favor of another method like Magic Auth. If this is the case for your application, you can skip dealing with passwords entirely.
If you have users who previously signed in using social auth providers, such as Google or Microsoft, those users can continue to sign in with those providers after you’ve migrated to WorkOS.
Check out our integrations page for guidance on configuring the relevant provider’s client credentials in WorkOS.
After your provider is configured in WorkOS, users can sign in with their provider credentials and will be automatically linked to a WorkOS user. WorkOS uses the email address from the social auth provider to determine this match.
Some users may need to verify their email address through WorkOS if email verification is enabled in your WorkOS environment’s authentication settings.
Email verification behavior varies depending on whether the provider is known to verify email addresses. For example, users signing in using Google OAuth and a gmail.com email domain will not need to perform the extra verification step.
Many applications allow users to sign up at any time. If your app offers this feature, then you should consider the timing of your migration. If any users sign up after you’ve completed importing users into WorkOS, but before you’ve switched to WorkOS for authentication, then those users will have been omitted from the migration process.
There are two main strategies to handle this:
The simplest solution is to schedule an appropriate time for the migration and disable sign-up while in progress. This may be done using temporary code added to your application and controlled by a feature flagging system.
After the migration is complete, your application should be updated to perform authentication using WorkOS, and the sign-up flag block disabled. This helps to ensure the export/import process captures all active users.
For applications that want to avoid disabling sign-ups, a “dual-write” strategy can be used.
When a new user signs-up, in addition to creating a user record in the existing user store, the application should also create a matching record in WorkOS using the Create User API. As time passes, WorkOS will stay consistent with future new users, but a migration will still need to be performed for the historical set of users.
You will need to perform the same export and import process into WorkOS, but keeping in mind that some users will already exist in WorkOS as a result from the “dual-write”.
While this minimizes forms of downtime for your application, there are other complications. For example, if a user updates their email or authentication method, you will need to perform the same update in WorkOS, at least until the migration process is complete.
Which to choose?
Your timeline for completing the migration, along with your user’s tolerances for disruption, will affect which strategy makes more sense for your application.
Disabling sign-ups, or even sign-in entirely, and doing a “big-bang” migration by moving all users at the same time, could be reasonable for a smaller application. However, larger applications that are on the critical path for their customers may need a more careful path in order to provide consistent access.
User management migration complexity can vary, so it is important to consider how existing application constraints will transfer to WorkOS. If you have any questions, reach out to support@workos.com or via your team’s WorkOS Slack channel for more help planning your migration.