User migration

Logto supports manual migration of existing users from another platform, this guide will show you how to import existing users via Management API and talk about things that you should consider before migrating.

User schema

Before we start, let's take a look at the user schema in Logto. There are 3 parts of the user schema that you should be aware of:

1. Basic data: is the basic info from the user profile, you can match the data from your existing user profile.
2. Custom data: stores additional user info, you can use this to store files that are unable to match the basic data.
3. Social identities: stores the user info retrieved from social sign-in.

You can create a map to match the user info from your existing user profile to basic data and custom data. For social sign in, you'll need additional steps to import the social identities, please refer to the API of Link social identity to user.

Password hashing

Logto uses Argon2 to hash the user's password, and also supports other algorithms like MD5, SHA1, SHA256 and Bcrypt for the convenience of migration. Those algorithms are considered insecure, the corrosponding password hashes will be migrated to Argon2 upon the user's first successful sign in.

If you need support for any particular hashing algorithm, please let us know.

Steps to migrate

1. Prepare the user data You should first export the user data from your existing platform, and then map the user info to the Logto user schema. We recommend you to prepare the mapped data in a JSON format. Here is an example of the user data:

   [
     {
       "username": "user1",
       "passwordDigest": "password-encrypted",
       "passwordAlgorithm": "SHA256"
     },
     {
       "username": "user2",
       "passwordDigest": "password-encrypted",
       "passwordAlgorithm": "SHA256"
     }
   ]

2. Create a Logto tenant You'll need to setup a tenant in Logto. You can use either Logto Cloud or Logto OSS. If you haven't done this yet, please refer to the Set up Logto cloud guide.

3. Setup the connection of Management API We'll use the Management API to import the user data, you can refer to the Management API to learn how to setup the connection in your development environment.

4. Import the user data It is recommended to prepare a script to import the user data one by one, we'll call create user API to import the user data. Here is an example of the script:

   const users = require('./users.json');
   
   const importUsers = async () => {
     for (const user of users) {
       try {
         await fetch('https://[tenant_id].logto.app/api/users', {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
             Authorization: 'Bearer [your-access-token]',
           },
           body: JSON.stringify(user),
         });
         // Sleep for a while to avoid rate limit
         await new Promise((resolve) => setTimeout(resolve, 200));
       } catch (error) {
         console.error(`Failed to import user ${user.username}: ${error.message}`);
       }
     }
   };
   
   importUsers();

Please noted that the API point is rate limited, you should add a sleep between each request to avoid the rate limit. Please review our rate limits page for details.

If you have a large amount of user data (100k+ users), you can reach out to us to increase the rate limit.