Update Role Scopes API

Replaces the full set of permission scopes assigned to a custom RBAC role.

Use this endpoint after creating a new role to add its initial scopes, or to update an existing role's permissions when access requirements change.

About Update Role Scopes

Scopes define the specific actions a custom role grants — such as reading device data, issuing commands, or managing groups. This endpoint performs a full replacement of a role's scope set; any scopes not included in the request will be removed. Scopes can be specified either by UUID (scope_ids) or by name string (scope_names). A newly created role has no scopes by default and must be populated via this endpoint before it grants meaningful access to assigned users.

Key Fields / Request Body

scope_ids — array of scope UUIDs to assign to the role

scope_names — array of scope name strings to assign; valid values include read:device, read:group, read:blueprint, read:directory_record, and a range of create:device_command:* and create:group_command:* action scopes

Common Use Cases

Populating a newly created role with its initial permission set

Expanding a role's permissions after a team's responsibilities grow

Narrowing a role's permissions during an access review by replacing the scope set with a reduced list

Best Practices

Treat every call to this endpoint as a full replacement — always include the complete intended scope set, not just the scopes you want to add

Use GET /authz2/v1/roles/{role_id}/scopes first to retrieve the current scope set before making changes, to avoid accidentally removing permissions

Use scope_names rather than scope_ids in automation where possible — names are stable and human-readable, making scripts easier to maintain

After updating scopes, verify the change took effect via GET /authz2/v1/roles/{role_id}/scopes

Workflow

Call GET /authz2/v1/roles/{role_id}/scopes to retrieve the current scope set

Build the updated scope list, including all scopes that should remain plus any new additions

PUT to this endpoint with the full intended scope set as scope_names or scope_ids

Confirm the updated scopes via GET /authz2/v1/roles/{role_id}/scopes