# Updating roles and scopes for an existing user group

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 `isUnmodifiable` is `false`). 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 |
|  --- | --- | --- | --- |
| 1. 
 | [List user groups for company](/openapi/rbacapi/user-groups/listusergroupsforcompany) | `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). |
| 1. 
 | [Get user group](/openapi/rbacapi/user-groups/getusergroup) | `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. |
| 1. 
 | [List user group roles](/openapi/rbacapi/roles/listusergrouprolesv3) | `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). |
| 1. 
 | [List user roles for company](/openapi/rbacapi/roles/listrolesv3) | `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). |
| 1. 
 | [Update user group roles](/openapi/rbacapi/roles/updateusergrouprolesv3) | `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](/guides/rbac_guides/rbac_scope_predicates_guide) 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. |
| 1. 
 | [List user group roles](/openapi/rbacapi/roles/listusergrouprolesv3) (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. |