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
andgroups.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.
Login flow for synced users
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 theemails
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 theemails
in the sync request, CodeCanvas will assign theexternalId
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 theemails
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 theemails
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 theusersPendingDeletion
list. You can delete them later using theDELETE /users/{id}
API or by rerunning the sync withdeleteMissingUsers: 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>, ... ] }