Migrating to passwordless authentication can be easier than you think! Since Passage doesn’t store any secret data (e.g. passwords, passkeys, biometrics), the only information you are required to transfer is the email addresses or phone numbers for your users (whichever you use as the identifier). In this post we will cover paths for two scenarios:
This is best for apps without a large legacy codebase and complex user model. Since you are leveraging Passage as the source of truth for all user data, this is the simplest migration path. At a high level, you will create your desired metadata schema for any user data you want to store. Then you will use the Passage API or the Import Users functionality in Console to migrate all of your user data.
In the Passage Console, create metadata fields for any user data you want to store beyond our standard identifiers. This is typically public information like names, but could also be internal information like roles or group IDs. Learn all about this by reading our guide here. This schema should be created before uploading users to ensure that all data gets properly imported.
You can do this via the Console or the Management API. If you use the Console, the Import Users button will provide you a template CSV file with all the fields you need to provide. Fields can be left blank if you don't have information for all users. Fill out and upload the CSV file to Passage.
Once complete, your users can successfully sign in and register with Passage! Follow the Passage Quickstart Docs to setup your front-end and back-end.
This is best for apps with a complex user model, enabling you to leverage Passage for passwordless authentication while you migrate user management over time. Passage will perform authentication while keeping your user model up to date as the source of truth for your application logic.
For this use case, you will only need to import user identifiers (e.g. emails or phone numbers) into Passage. You can do this via the Console or the Management API. If you use the Console, the import users button will provide you a template CSV file. Fill out and upload the CSV file to Passage.
Once users are uploaded, you can either use the response from the Import API or List Users API endpoint to get a list of users and their Passage ID's. Perform a schema migration to add a passage_id column to your users table, then populate the new column with the results of the above API operation.
Note: You could also update the users' Passage ID in an on-demand fashion the next time they login using the backend SDKs.
For the most part, you can implement the backend auth middleware using the same pattern you would for any Passage application. You can see examples for the supported languages here.
The main difference is that the middleware will need to set the user context based on the application's user table after authenticating with Passage. To account for new and existing users, you will want to implement a function that gets the user information based on the Passage ID if it exists, or creates a new user. This allows you to set your user data on the request context and ensures that a user is created on your model if they register after the initial one time user import. The middleware would look like this:
Managing User Updates
If you choose to use the Passage Profile element to allow your users to manage their identifiers and devices, we recommend checking the user information via the Passage SDK before sending emails to the user for other purposes.
Once Passage is live on your site, each of your users will need to login on their next visit. On first login attempt they will be prompted to go through a magic link flow to verify their identity and add a device to their account to use for sign-in. No password reset flow is needed!
Regardless of which approach you take, communicating with your users is critical to ensuring a good experience and smooth transition. We recommend including a quick intro on your login and registration pages to explain the change. Here’s an example:
We are excited to help you give your users the best possible login experience. Contact us at support@passage.id if you have questions or would like some assistance with the migration process.