---
title: "Update Role Scopes API"
method: PUT
path: "/authz2/v1/roles/{role_id}/scopes"
tags: ["esper_cloud_api_Roles"]
---

# Update Role Scopes API

`PUT /authz2/v1/roles/{role_id}/scopes`

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

## Path parameters

- `role_id` string, uuid, required

## Request body

- object
  - `scope_ids` string[]
  - `scope_names` string[]

## Response `200`

Request Succeded

- object
  - `count` integer
  - `scopes` EsperCloudApiScopeResponse[]
    - `id` string
    - `name` string
    - `description` string
    - `scope_type` integer

## Other responses

- `400` — Bad request
- `401` — Unauthorized request

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/versions/e1f64cbb488e/schema)