The steps below explain how to move a user from one user group (the source group) to another user group (the target group) within the same company. This is useful when a user's role or department changes and you want them to inherit a different set of permissions.
Note: Users can belong to multiple user groups simultaneously, and all roles and scopes across groups are additive (the user inherits all the roles and scopes). This workflow is intended for scenarios where you want to intentionally remove a user from one group and place them in another. If you simply want to add a user to an additional group without removing them from their current group, refer to the Adding a user to an existing user group workflow instead.
| Step | Name | Endpoint | Details |
|---|---|---|---|
| List user groups for a company | POST /v3/companies/{companyId}/user-groups/list | List all available user groups for the company to identify the source group (the group the user currently belongs to) and the target group (the group the user should be moved to). URL path requires: companyId.Request body requires: pagination (with offset and limit). Optionally, provide searchText for search, sortParams to sort by NAME or CREATED_AT, and filters to filter by specific userGroupIds.Response will contain: userGroups (an array of user group objects each containing id, name, description, companyId, isUnmodifiable, createdAt, updatedAt, createdBy, and updatedBy).Other APIs will use: userGroups > id (referred to as groupId in subsequent steps). | |
| List source group members | POST /v3/companies/{companyId}/user-groups/{groupId}/members | View the current members of the source group to confirm that the user you intend to transfer is a member. URL path requires: companyId and groupId (the source group ID from Step 1).Response will contain: members (an array of member objects each containing userId and addedAt).Other APIs will use: members > userId (the ID of the user to be transferred). | |
| List target group members (optional) | POST /v3/companies/{companyId}/user-groups/{groupId}/members | View the current members of the target group to confirm that the user is not already a member. URL path requires: companyId and groupId (the target group ID from Step 1).Response will contain: members (an array of member objects each containing userId and addedAt) and pagination with totalNumResults. If the user already exists in the target group, you may only need to remove them from the source group in Step 4. | |
| Remove user from source group | PATCH /v3/companies/{companyId}/user-groups/{groupId}/members | Remove the user from the source group. URL path requires: companyId and groupId (the source group ID from Step 1).Request body requires: userIdsToAdd (pass an empty array since you are only removing), and userIdsToRemove (an array containing the userId of the user being transferred, from Step 2).Note: Once removed, the user will lose all roles and permissions inherited through the source group. If the user has access to the same role through another group or as a result of a direct assignment, those permissions will be retained. Response will contain: a 200 status code confirming the members were updated successfully. | |
| Add user to target group | PATCH /v3/companies/{companyId}/user-groups/{groupId}/members | Add the user to the target group. URL path requires: companyId and groupId (the target group ID from Step 1).Request body requires: userIdsToAdd (an array containing the userId of the user being transferred) and userIdsToRemove (pass an empty array since you are only adding).Note: The user must belong to the same company as the target user group. Once added, they will automatically inherit all roles and scopes assigned to the target group. Response will contain: a 200 status code confirming the members were updated successfully. | |
| List user groups for user | POST /v3/users/{userId}/user-groups | Verify the transfer by listing all user groups the user belongs to. URL path requires: userId.Response will contain: userGroups (an array of user group objects that the user is a member of). The target group should now appear in this list and the source group should no longer be present, confirming that the user has been successfully transferred and now inherits the target group's roles and scopes. |