docs: migration

docs/docs/recipes/interact-with-management-api/README.md

@@ -84,3 +84,11 @@ There are 2 optional query parameters:
 
 - `page`: indicates the page number, starts from 1, the default value is 1.
 - `page_size`: indicates the number of items per page, the default value is 20.
+
+## Rate limit
+
+:::note
+This is only for Logto Cloud.
+:::
+
+To ensure the reliability and security of our services for all users, we employ a general firewall that monitors and manages traffic to our website. While we do not enforce a strict rate limit, we recommend that users limit their activity to approximately 200 requests every 10 seconds to avoid triggering our protective measures.

docs/docs/recipes/migrations/README.mdx

@@ -0,0 +1,89 @@
+---
+sidebar_position: 14
+---
+
+import Availability from '@components/Availability';
+
+# 🔄 Migrate to Logto
+
+<Availability cloud oss />
+
+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](../../references/users/#profile) 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](https://openapi.logto.io/operation/operation-post-api-users-parameter-identities).
+
+## Password hashing
+
+Logto uses [Argon2](https://en.wikipedia.org/wiki/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](https://logto.io/contact).
+
+## 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:
+
+```json
+[
+  {
+    "username": "user1",
+    "passwordEncrypted": "password-encrypted",
+    "passwordEncryptionMethod": "SHA256"
+  },
+  {
+    "username": "user2",
+    "passwordEncrypted": "password-encrypted",
+    "passwordEncryptionMethod": "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 [Getting Started](../../tutorials/get-started/) 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](../../recipes/interact-with-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](https://openapi.logto.io/operation/operation-post-api-users) API to import the user data. Here is an example of the script:
+
+```javascript
+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](../interact-with-management-api/#rate-limit) page for details.
+
+If you have a large amount of user data (100k+ users), you can [reach out to us](https://logto.io/contact) to increase the rate limit.