Skip to main content

Migrate your existing identities

With authentication now set up on your frontend and backend, the next step is to prepare your existing user identities for migration. You should have already chosen your identity migration strategy in Phase 1: Plan and prepare; "bulk" or "graceful" migration. You will now implement your chosen identity migration strategy.

Bulk import of identities​

If you're using a managed identity solution, it’s a good idea to start the export of existing identities early, especially if there's no straightforward way to export the identities and you might need to go through a support process. Identify the hashing algorithm used for credentials—if your passwords aren't hashed, Ory handles hashing automatically during import. If Ory supports your hashing algorithm, use the create identity API to import users. If the hashing algorithm isn't supported or if you can't get the hashed passwords from your current authentication system, you may want to do a "graceful" migration.

The create identity API supports bulk imports with a maximum of 1000 identities per request—larger imports require multiple requests. The endpoint accepts a JSON array of identities, each of which must have a create property that holds the identity that should be created. See the Import identities documentation for complete details.

Graceful import of identities​

Ory does not support the direct import of active sessions from your existing system. To ensure that users with active sessions from the old system can continue accessing your services without needing to reauthenticate immediately, implement a transition period during which both the old and new systems operate concurrently. During this period, use the password migration hook to migrate your existing users. All user authentication flows—including login, registration, password recovery, and settings management—should be managed by Ory. However, your backend must be configured to recognize and accept sessions from both the old system and Ory. As the transition progresses, gradually phase out the old system. Once most or all active sessions from the old system have expired or been replaced by new sessions in Ory, you can complete the migration to Ory exclusively. This gradual approach minimizes user disruption and provides your development team with the time needed to resolve any potential issues that may arise during the migration.