Migrate users to Identity Pools

Learn how to migrate users from external CIAM platforms into your Identity Pool using dedicated APIs. Change your CIAM platform to securely and reliably store user data, maintaining performance and integrity even at large scales.

About migrating users

You can import users into the SecureAuth Identity Pool for a tenant. If your current CIAM solution outside of SecureAuth doesn't meet your needs, consider migrating external users to Identity Pools for secure and scalable storage.

To migrate users, use the SecureAuth Import Identity Tenant API.

You can also migrate users between tenants and Identity Pools. To do this, use the Export Identity Tenant API followed by the Import Identity Tenant API. However, exporting users is not recommended for production environments.

Prerequisites

An Identity Pool for importing or exporting user data
Access to the System workspace
A client application in the System workspace with the manage_configuration scope to obtain an access token for user import
Note
The
The Preconfigure your workspace section describes how to create a client application for the Admin workspace and admin APIs. To proceed, create a similar application in the System workspace and assign it the manage_configuration scope.

Prepare input data for import

Prepare import data
- Format your data according to the the Import Tenant Configuration API. See the Request Body Schema for details.
- Organize users into batches of up to 100 users per request, including credentials, identifiers, and addresses.
Generate unique IDs
- Create random unique IDs (preferably version 4 UUIDs) for each user and related objects:
  - users – Core user information
  - user_credentials – User login credentials. Include id and map to user_id.
  - user_identifiers – Login identifiers (email or phone). Include id and map to user_id.
  - user_verifiable_addresses – Contact information (email or mobile). Include id and map to user_id.
Optional: Handle password expiry
- To migrate users without passwords, set the expires_at parameter to a past date. This ensures expired credentials, requiring users to reset passwords upon login.
  When you migrate users without passwords, login attempts using the OAuth2 Resource Owner Password flow fail with the credential expired error, returning the following response:
```
{"error_description":"request lacks valid authentication credentials for the target resource","error_hint":"credential expired","status_code":401}                        
```
  The same ("error_description": "credential expired") also occurs if users try to change or verify their password.
  To resolve this, users must request an OTP for password reset (forgot? in the login UI) and complete the password reset process.
- When expires_at is not set or is set to 1900-01-01T00:00:00Z, the password never expires.
Run imports
- Submit import requests, with up to 8 parallel requests for optimal performance (~1.5 million users in 30 minutes).
Retry failed requests
- Use the unique IDs to ensure API idempotency, avoiding duplicate records if you need to reattempt an import.

Here is a sample payload that follows the schema outlined above, for two users with their credentials, identifiers and addresses:

{
"user_credentials": [
   {
         "created_at": "2022-08-03T11:03:38.34+02:00",
         "expires_at": "2019-08-24T14:15:22Z",
         "id": "e89e254c-f538-4ae2-9150-4d4580bcf886",
         "payload": {
            "hashed_password": {
               "config": {
                     "method": "sha",
                     "sha": {
                        "function": "SHA-256",
                        "salt": "lJgayFHwYelZGmrBnYqt",
                        "salt_length": 20
                     }
               },
               "value": "eUJBxl+dwVjPgwC2cm1K+hYNWFRly/RdCT/bgmIBowo="
            }
         },
         "tenant_id": "default",
         "type": "password",
         "updated_at": "2022-08-03T11:03:38.34+02:00",
         "user_id": "58e6184f-8e38-4193-b889-965b34326c7f",
         "user_pool_id": "caku6lrphdd3cfqro3mg"
   },
   {
         "created_at": "2022-08-03T11:03:38.343+02:00",
         "id": "20f45596-f407-495c-aa45-043609ae2280",
         "payload": {
            "hashed_password": {
               "config": {
                     "method": "sha",
                     "sha": {
                        "function": "SHA-256",
                        "salt": "lJgayFHwYelZGmrBnYqt",
                        "salt_length": 20
                     }
               },
               "value": "eUJBxl+dwVjPgwC2cm1K+hYNWFRly/RdCT/bgmIBowo="
            }
         },
         "tenant_id": "default",
         "type": "password",
         "updated_at": "2022-08-03T11:03:38.343+02:00",
         "user_id": "cdcb7a5b-a726-404c-ba66-b8552d9be8fc",
         "user_pool_id": "caku6lrphdd3cfqro3mg"
   }
],
"user_identifiers": [
   {
         "created_at": "2022-08-03T11:03:38.341+02:00",
         "id": "b7108442-7f1e-40b9-a4d9-0c9ab3b0d18b",
         "identifier": "user0@example.com",
         "tenant_id": "default",
         "type": "email",
         "updated_at": "2022-08-03T11:03:38.341+02:00",
         "user_id": "58e6184f-8e38-4193-b889-965b34326c7f",
         "user_pool_id": "caku6lrphdd3cfqro3mg"
   },
   {
         "created_at": "2022-08-03T11:03:38.343+02:00",
         "id": "cb1b6524-a769-442a-8b80-fe62ed9ed614",
         "identifier": "user1@example.com",
         "tenant_id": "default",
         "type": "email",
         "updated_at": "2022-08-03T11:03:38.343+02:00",
         "user_id": "cdcb7a5b-a726-404c-ba66-b8552d9be8fc",
         "user_pool_id": "caku6lrphdd3cfqro3mg"
   }
],
"user_verifiable_addresses": [
   {
         "address": "user0@example.com",
         "created_at": "2022-08-03T11:03:38.342+02:00",
         "id": "0b24d104-3d0e-40d7-bd2d-ac1e74b8fb34",
         "status": "active",
         "tenant_id": "default",
         "type": "email",
         "updated_at": "2022-08-03T11:03:38.342+02:00",
         "user_id": "58e6184f-8e38-4193-b889-965b34326c7f",
         "user_pool_id": "caku6lrphdd3cfqro3mg",
         "verified": true
   },
   {
         "address": "user1@example.com",
         "created_at": "2022-08-03T11:03:38.343+02:00",
         "id": "f0eedf44-f7d8-4401-9a0d-4a02d3ed92f4",
         "status": "active",
         "tenant_id": "default",
         "type": "email",
         "updated_at": "2022-08-03T11:03:38.343+02:00",
         "user_id": "cdcb7a5b-a726-404c-ba66-b8552d9be8fc",
         "user_pool_id": "caku6lrphdd3cfqro3mg",
         "verified": true
   }
],
"users": [
   {
         "created_at": "2022-08-03T11:03:38.33+02:00",
         "id": "58e6184f-8e38-4193-b889-965b34326c7f",
         "metadata": {
            "groups": [
               "admins",
               "users"
            ]
         },
         "metadata_schema_id": "default_metadata",
         "payload": {
            "name": "Keshia Mraz",
            "given_name": "Keshia",
            "family_name": "Mraz"
         },
         "payload_schema_id": "default_payload",
         "status": "active",
         "status_updated_at": "2022-08-03T11:03:38.33+02:00",
         "tenant_id": "default",
         "updated_at": "2022-08-03T11:03:38.33+02:00",
         "user_pool_id": "caku6lrphdd3cfqro3mg"
   },
   {
         "created_at": "2022-08-03T11:03:38.343+02:00",
         "id": "cdcb7a5b-a726-404c-ba66-b8552d9be8fc",
         "metadata": {
            "groups": [
               "users"
            ]
         },
         "metadata_schema_id": "default_metadata",
         "payload": {
            "name": "Vicente Moen",
            "given_name": "Vicente",
            "family_name": "Moen"
         },
         "payload_schema_id": "default_payload",
         "status": "active",
         "status_updated_at": "2022-08-03T11:03:38.343+02:00",
         "tenant_id": "default",
         "updated_at": "2022-08-03T11:03:38.343+02:00",
         "user_pool_id": "caku6lrphdd3cfqro3mg"
   }
]
}

Manage tenant user data

Use the System API to import or export users for a specific tenant.

Import users

Get an access token.

Call the OAuth 2.0 token endpoint as the System client obtain an access token with the manage_configuration scope.

curl --location --request POST 'https://example.com/tenant_id/system/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=value' \
--data-urlencode 'client_secret=secret'

Result: The token is returned and includes the manage_configuration scope.

Need help? See the Call the token endpoint section in Call Token Endpoint.

Import user data.
- Call the Import Tenant Configuration endpoint and include the user data in the request body:
```
curl --location --request PUT 'https://example.com/api/identity/system/{tid}/configuration' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-d @configuration.json                     
```
- Replace {tid} with your tenant ID and {ACCESS_TOKEN} with the token from the first step.
- Include the user data payload directly in the request body or reference a JSON file with the -d @YourFileName.json parameter.
Result: A 204 NO CONTENT response confirms your tenant configuration is successfully imported and available.

Export users

Warning

The Export API is not production-ready for large user bases. Use it only for testing or beta purposes.

Get an access token.

Call the OAuth 2.0 token endpoint as the System client obtain an access token with the manage_configuration scope.

curl --location --request POST 'https://example.com/tenant_id/system/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=value' \
--data-urlencode 'client_secret=secret'

Result: The token is returned and includes the manage_configuration scope.

Need help? See the Call the token endpoint section in Call Token Endpoint.

Export user data.
- Call the Export Tenant Configuration endpoint to retrieve user data:
```
curl --location --request GET 'https://example.com/api/identity/system/{tid}/configuration' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'                     
```
- Replace {tid} with your tenant ID and {ACCESS_TOKEN} with the token from the first step.
Result: A 200 OK response returns your tenant configuration, including Identity Pools and their users, as JSON is in the response body.

Insert mode

The import endpoint includes an optional mode query parameter to handle conflicts when importing user records. For example, if a user already exists in SecureAuth with the same ID as a user in your import, the mode parameter determines how SecureAuth processes the request:

mode=ignore (default) – SecureAuth ignores any conflicting changes from the import.
mode=fail – SecureAuth stops the import process and returns an error.
mode=update – SecureAuth updates the existing user record with the values provided in the import request.

In this section: