The steps below explain how to view the current roles assigned to a user group, browse available roles for the company, and update the group's role and scope assignments.
Note: This workflow applies only to custom user groups (where
isUnmodifiableisfalse). Standard (platform-created) user groups cannot have their roles and scopes modified. To customize them, duplicate the desired standard group by creating a new custom user group (based on the system-defined group) and modify the desired role assignments as needed.
| Step | Name | Endpoint | Details |
|---|---|---|---|
| List user groups for company | POST /v3/companies/{companyId}/user-groups/list | List all available user groups for a company to identify the group you want to update. URL path requires: companyId.Request body requires: pagination (with offset and limit). Optionally, provide searchText for case-insensitive 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) and pagination with totalNumResults.Other APIs will use: userGroups > id (referred to as groupId in subsequent steps). | |
| Get user group | GET /v3/companies/{companyId}/user-groups/{groupId} | View the details of the target user group to confirm its identity and check whether it is modifiable. URL path requires: companyId and groupId.Response will contain: the full user group object including id, name, description, companyId, isUnmodifiable, createdAt, updatedAt, createdBy, and updatedBy.Note: If isUnmodifiable is true, the group is a standard (platform-created) user group. Its name, description, and assigned roles and scopes cannot be changed. To customize roles and scopes based on a standard group, duplicate it by creating a new custom user group and copying the desired role assignments. Only custom user groups (where isUnmodifiable is false) can have their roles and scopes updated. | |
| List user group roles | POST /v3/companies/{companyId}/user-groups/{groupId}/roles | View the roles currently assigned to the user group. This step helps you understand the existing role and scope assignments before making changes. URL path requires: companyId and groupId.Request body requires: pagination (with offset and limit). Optionally, provide searchText, sortParams to sort by NAME, and filters to filter by roleIds or roleProvidedBy (values: PLATFORM or COMPANY).Response will contain: roles (an array of role objects each containing role details with id, name, description, isPlatformRole, permissions, and associated scope with audiences and predicates).Other APIs will use: role > id (the roleId of any roles you want to remove in Step 5). | |
| List user roles for company | POST /v3/companies/{companyId}/roles | Browse all available roles for the company to identify new roles you want to assign to the user group. You can filter to view only platform-provided roles, only custom company roles, or both. URL path requires: companyId.Request body requires: pagination (with offset and limit). Optionally, provide searchText, sortParams to sort by NAME, and filters with roleProvidedBy (values: PLATFORM, COMPANY) or specific roleIds.Response will contain: roles (an array of role objects each containing id, name, description, isPlatformRole, companyId, permissions with permission name and actions, createdAt, updatedAt, createdBy, and updatedBy).Other APIs will use: roles > id (the roleId of any roles you want to add in Step 5). | |
| Update user group roles | PATCH /v3/companies/{companyId}/user-groups/{groupId}/roles | Add new roles with scopes and/or remove existing roles from the user group. URL path requires: companyId and groupId.Request body requires: rolesToAdd. The rolesToAdd is an array of objects, each containing the roleId from Step 4 and a scope object defining the audiences with predicates. Each predicate specifies a type such as BOOKING_TMC, CONTRACTING_TMC, COMPANY, LEGAL_ENTITY, PROFILE, or STEALTH_TYPE, and an optional id for the target entity.Note: See the access with multiple scope predicates guide if you're adding multiple scopes to a role. Response will contain: a 200 status code confirming the user group roles were updated successfully. | |
| List user group roles (optional) | POST /v3/companies/{companyId}/user-groups/{groupId}/roles | Verify the updated role assignments by listing the roles for the user group again. URL path requires: companyId and groupId.Request body requires: pagination (with offset and limit).Response will contain: roles (the updated array of role objects with their associated scope information). The newly added roles and scopes from Step 5 should now appear in this list, and any removed roles should no longer be present. |