User Migration

The user migration is often the first part of setting cidaas live. Therefore it is important to have a step by step guide, how to start to migrate the users, how to map the data and what are the issues you need to address during migration.

Migration Procedures

For decision making how to go live, the documentation for one-time-migration, bidirectional-sync or long-term migration is more helpful.

Term	Description
API endpoint	POST {your-domain}/users-srv/user/bulk — Bulk User Migration API
Batch size	Maximum 1000 users per request; prefer smaller batches (e.g. 50–100) with a queue for large migrations
Security by Scope	Requires cidaas:bulk_user_create.
Security by Config	Separately, migrationMode must be enabled if you need to overwrite passwords on users that were already migrated

Prerequisites

Before starting the Bulk User Import, ensure the following requirements and client configurations are satisfied:

• OAuth2 Client & Scope: Configure a NON_INTERACTIVE App with the cidaas:bulk_user_create scope.
• Password Overwrite (migrationMode): If you need to overwrite existing user passwords during re-migration, enable migrationMode for the client.
• Disposable Email Configuration: By default, allow_disposable_email is disabled, so disposable/throw-away email domains are blocked. If disposable or test email addresses (such as mailinator.com or yopmail.com) are expected during migration or testing, enable allow_disposable_email through the Create User App Setup API. When disabled, cidaas rejects disposable emails with an "invalid email passed" error (code 507, status 400). The setting is reversible — you can enable or disable it again later through the User Setup API. It is not available in Trustdesk or App Settings.
• Email Domain MX Record Validation: Ensure that email domains in your migration batch possess valid and resolvable DNS MX or A records. Domains with missing or invalid MX records will fail email validation during import.

Step 1. Determine the information to migrate

Verify the information you would like to migrate.

Question	Description
Which information are you going to migrate	e.g. email, mobile_number, password_hash_info, createdTime, lastLoggedInTime. Those are so called system fields. You need to ensure those are enabled in the field setup
Do you also migrate account timestamps?	Optional: createdTime (original registration date) and lastLoggedInTime (last login in the source system) on the user account. See Account timestamps below.
Do you also migrate customFields?	If you have custom information that is not covered by the system information you can create your own custom fields. This you need to provide in the customFieldsas key-value Pair.
Do you want to migrate users, that have multiple providers?	If you want to migrate users which can have two or more providerinformation e.g. facebook, google and a password, you need to use the identities array. UserEntity

Step 2. Create a Token using the client credentials Token

To Create a Token using the Client Credentials OAuth2 Flow, you can find a flow chart and API Explantion here

Please ensure that your App is having the proper scope cidaas:bulk_user_create and create a NON_INTERACTIVE App, which can be called user-migration. To create your first App, you can use this guidance.

Step 3. Integrate the User Bulk API

1. You will need to get the data from your data source
2. Map the incoming (source) data to a structure described in the Bulk API
3. Add the Token generated in Step 2. as Authorization: Bearer eyxxxx Header
4. Call the API via Post Call

The simplest json is this one:

{
  "userStatus": "VERIFIED",
  "sub": "8dfc4306-9f3b-4a33-95d0-98c8954da2c1",
  "email": "[email protected]",
  "password_hash_info": {
    "algorithmTypeId": "BCRYPT_10",
    "passwordHash": "$2b$10$EfrjjYYGih4j4AbnpIWT2OEjvvRoYNBDJ0Wv2E.MwE/oZ87hasAHi"
  },
  "provider": "self",
  "createdTime": "2019-08-24T14:15:22Z",
  "lastLoggedInTime": "2023-06-15T15:24:19.378Z"
}

Account timestamps

When your source system stores registration or last-login dates, include them on each user entity so admin views and reporting stay accurate after migration.

Field	When to send	Behavior
createdTime	Original account registration date from the legacy system	Applied when the user account is created. Mainly relevant for first-time migration of a user.
lastLoggedInTime	Last successful login in the legacy system	Create: uses your value when provided; otherwise cidaas sets the current time. Update: uses your value when provided; otherwise the existing value in cidaas is kept (not reset to the current time).

Use ISO 8601 date-time strings (for example 2023-06-15T15:24:19.378Z).

Validations	How to enable those
Missing required Fields	A useraccount must have a valid user identifier e.g. an email. Else the API will return a BAD_REQUEST (400)
Allow Disposable Emails and Validate Mobile Numbers	By default, allow_disposable_email is false, so disposable/throw-away email addresses in the import batch fail validation with "invalid email passed" (error code 507, HTTP status 400). For migration or test scenarios that require disposable emails, set allow_disposable_email: true through the Create User App Setup API. You can disable it again later. This setting is not available in Trustdesk or App Settings. Similarly, you can adjust mobile validation settings (validate_phone_number) to control phone number verification.
Invalid Datatype	Please ensure that you are providing the fields (custom and sytem fields) in the same datatype format that is set in the field setup. Any invalid value for datatype or invalid format can lead to failures during migration. Also disabled fields will be skipped
Invalid timestamp format	createdTime and lastLoggedInTime must be valid date-time values. Unparseable values may be ignored, and cidaas may fall back to default timestamp behavior for that field.

Troubleshooting Migration Failures

During user migration, the Bulk API performs validation checks on all incoming user records. If a record fails validation, the individual user migration attempt will fail with a FAILED process state and include a detailed error message in the message field.

Resolving "invalid email passed" Error

A common error encountered during batch imports is the following:

{
  "code": 507,
  "status": 400,
  "error": "invalid email passed"
}

Potential Root Causes

• Disposable/Temporary Email Domains: The email address uses a disposable/throw-away domain (e.g., mailinator.com, yopmail.com), and allow_disposable_email is disabled (the default). cidaas checks email domains against a centrally maintained disposable-email domain list (regularly updated) and also performs MX record validation.
• Incorrect Email Syntax: The email address is not well-formed according to RFC standards (e.g., missing @ symbol, spaces in the address, invalid characters).
• Domain DNS Validation Failure: cidaas verifies domain DNS MX/A records, and the domain of the email address is invalid or unresolvable.

Step-by-Step Resolution Guide

Follow these steps to verify and update your cidaas configuration or migration data:

Step 1: Check Allow Disposable Email (migration and test scenarios) If temporary or test emails in your migration batch are rejected as disposable, check the allow_disposable_email setting on the User Setup profile linked to your application:

1. By default, allow_disposable_email is disabled and disposable/throw-away domains are blocked.
2. When appropriate for migration or testing, enable it by setting user_setup.allow_disposable_email to true through the Create User App Setup API.
3. The setting is reversible — you can disable it again later through the User Setup API when disposable emails are no longer needed.
4. This setting is not available in Trustdesk or App Settings. Enabling it does not modify cidaas's centrally maintained disposable-email domain list.

Only enable disposable emails when your migration or test scenario requires them; do not enable them universally without that context.

Step 2: Sanitize migration batch data For production migrations, we recommend sanitizing email records before initiating the migration:

1. Ensure all email addresses conform to standard formatting (e.g., no leading/trailing spaces, contains a single @ sign, and has a valid top-level domain).
2. Filter out disposable/temporary email addresses from the export if your application restricts them for security.
3. Validate that the domains of the email addresses are active and have valid DNS MX or A records.

How cidaas uniquely identifies and updates the user if already migrated

Description	Example
Update users via sub	To update a user via sub, which remains stable, is the best way to re-migrate/update the useraccount and identities
Update via useridentifier combined with provider	If the sub is not provided, the incoming useridentifier like email as well as the provider e.g. facebook is search and the retrieved users sub will be set automatically by cidaas.

Add further identities to an existing user

If you migrate users with multiple providers, please ensure that you provide a sub, else it will lead to conflicts.

To prevent a conflict, if the user already exists you can do following:

1. Call the existence api by userId Link to API
2. Take the sub and set this in the requestBody for the bulk API.