List Role Scopes API

Returns the permission scopes currently assigned to a specific custom RBAC role.

Use this endpoint to inspect what actions a role grants before assigning it to a user, or to retrieve the current scope set before making updates.

About List Role Scopes

Each custom role in Esper has a set of scopes that define the actions users assigned to that role are permitted to perform — such as reading device data, issuing specific commands, or managing group membership. This endpoint returns those scopes as a scopes array alongside a count field. Results include each scope's UUID, name, description, and type. This is the reference endpoint to call before using PUT /authz2/v1/roles/{role_id}/scopes to modify a role's permissions.

Key Fields (Response)

id — the UUID of the scope; used with PUT /authz2/v1/roles/{role_id}/scopes when updating via scope_ids

name — the scope name string (e.g., read:device, create:device_command:REBOOT)

description — a human-readable description of what the scope permits

scope_type — integer indicating the type of scope

Common Use Cases

Auditing what permissions a role grants before assigning it to a user

Retrieving the current scope set as a baseline before updating it via PUT /authz2/v1/roles/{role_id}/scopes

Verifying that a scope update was applied correctly after calling the update endpoint

Best Practices

Always call this endpoint before PUT /authz2/v1/roles/{role_id}/scopes — since that endpoint performs a full replacement, knowing the current set prevents accidental permission removal

Use scope name values from the response to build human-readable access summaries for audit reports

Workflow

Call GET /authz2/v1/roles/{role_id}/scopes to retrieve all scopes currently assigned to the role

Review the name and description of each scope to confirm the role's permission set

Use the results as the baseline when preparing an update via PUT /authz2/v1/roles/{role_id}/scopes