Migrate and Sync Users from External Sources

To migrate and synchronize users and groups from an external source to CodeCanvas, you should use the /user-sync API endpoint.

Before you start an actual migration, we recommend that you test the API in the API Playground.

How it works

Async API

The /user-sync API is asynchronous. When you send a request to the endpoint, CodeCanvas validates the request, checks for duplicates and non-existing entities, and then starts the synchronization.
Only one sync request can be in progress at a time. If you send a new request while the previous one is still running, CodeCanvas will return an error.

Unique attributes

users.externalId and groups.externalId – a unique identifier for users and groups in the external source.
users.username – a unique name for the user in CodeCanvas.
users.emails – a list of unique email addresses for the user. These emails are automatically considered as verified.
groups.name – a unique name for the group in CodeCanvas.

Users created via /user-sync can log in to CodeCanvas only through an external identity provider – the built-in authentication is not available for such accounts.
During the first user login, CodeCanvas associates an existing account (created during the sync) with the user based on their email (any email from the emails list).

What happens if a user already exists

Matching externalId
If a user with the same externalId as in the sync request already exists, CodeCanvas will update the user's data with the new information. If the emails list is updated, the user will be required to re-log in to CodeCanvas.
No externalId, matching verified email
If an existing user has no externalId but has a verified email which matches one of the emails in the sync request, CodeCanvas will assign the externalId to this account.
No externalId, matching non-verified email
If an existing user has no externalId but has a non-verified email which matches one of the emails in the sync request, the API will log an error and skip this user. The existing user account remains unchanged.
No externalId, no matching email
If an existing user has no externalId and their email doesn't match any of the emails in the sync request, the API will log an error and skip this user. The existing user account remains unchanged.

How users are deleted

Suppose an already migrated user is deleted in the external system. In that case, the user account has an externalId in CodeCanvas but is not present in the sync request. During the sync, such users will be handled based on the optional deleteMissingUsers parameter in the request body.

deleteMissingUsers: false (default) – the users will be suspended (unable to perform any actions in CodeCanvas) but not deleted. The response will include such users in the usersPendingDeletion list. You can delete them later using the DELETE /users/{id} API or by rerunning the sync with deleteMissingUsers: true.
deleteMissingUsers: true – the users will be permanently deleted.

Migrate users

To use the /user-sync API for user migration (synchronization), create an application or shell script that sends requests to the endpoint. Make sure to run synchronization regularly to keep the user data up to date.

(Optional) We recommend that you permanently disable self-registration for the used authentication modules. This will ensure that all users are created only via the sync process. You can do this for each module in Administration | Auth Modules.
Prepare the data for synchronization. See the next step for the required attributes.
Start the sync by sending a POST request to the /user-sync endpoint. In the request body, provide data for all users and groups you want to migrate/sync.
POST /user-sync
For the full list of attributes and request examples, see the API Playground.
Request body:
{ "groups": [ { "externalId": <string>, "name": <string | unique>, "description": <string | optional> }, ... ], "users": [ { "externalId": <string>, "username": <string | unique>, "emails": [ // user emails <string | unique>, ... ], "firstName": <string>, "lastName": <string>, "groups": [ // optional "group1", // group external id "group2" ] }, ... ], "deleteMissingUsers": <boolean | optional> }
Response:
{ "id": <string>, "status": <enum (IN_PROGRESS | COMPLETED | ABORTED | FAILED)>, "createdAt": <datetime>, "finishedAt": <datetime | optional>, "usersCreated": <int>, "usersUpdated": <int>, "usersDeleted": <int>, "usersPendingDeletion": [ // optional <string>, ... ], "groupsCreated": <int>, "groupsUpdated": <int>, "groupsDeleted": <int>, "groupMembershipsCreated": <int>, "groupMembershipsDeleted": <int>, "errorMessages": [ // optional <string>, ... ] }
Monitor the sync status by sending a GET request to the /user-sync/{id} endpoint. The response will contain the current status of the sync.
GET /user-sync/{id}
For request examples, see the API Playground.
Response:
{ "id": <string>, "status": <enum (IN_PROGRESS | COMPLETED | ABORTED | FAILED)>, "createdAt": <datetime>, "finishedAt": <datetime | optional>, "usersCreated": <int>, "usersUpdated": <int>, "usersDeleted": <int>, "usersPendingDeletion": [ // optional <string>, ... ], "groupsCreated": <int>, "groupsUpdated": <int>, "groupsDeleted": <int>, "groupMembershipsCreated": <int>, "groupMembershipsDeleted": <int>, "errorMessages": [ // optional <string>, ... ] }
If necessary, you can cancel the sync by sending a POST /user-sync/{id}/abort request. Users and groups that have already been created/updated/deleted will remain in CodeCanvas.
POST /user-sync/{id}/abort
For request examples, see the API Playground.
Response:
{ "id": <string>, "status": <enum (IN_PROGRESS | COMPLETED | ABORTED | FAILED)>, "createdAt": <datetime>, "finishedAt": <datetime | optional>, "usersCreated": <int>, "usersUpdated": <int>, "usersDeleted": <int>, "usersPendingDeletion": [ // optional <string>, ... ], "groupsCreated": <int>, "groupsUpdated": <int>, "groupsDeleted": <int>, "groupMembershipsCreated": <int>, "groupMembershipsDeleted": <int>, "errorMessages": [ // optional <string>, ... ] }

Last modified: 18 September 2024