List Roles API

Returns all custom RBAC roles defined for the tenant.

Use this endpoint to enumerate available roles before assigning one to a user, or to audit the set of custom roles that have been created for fine-grained access control.

About List Roles

Esper's authorization service supports custom roles as an alternative to the built-in fixed roles. Each custom role has a name, description, and a set of scopes that define what actions users assigned to that role can perform. This endpoint returns all custom roles for the tenant as a roles array alongside a count field. Role IDs returned here are used with PUT /authz2/v1/users/{user_id} when assigning an AuthZ Role User and with the role detail and scopes endpoints for management.

Key Fields (Response)

id — the UUID of the role; used in all subsequent role management and user assignment calls

name — the display name of the role

description — a human-readable description of the role's intended purpose

role_type — integer indicating the type of role

Common Use Cases

Enumerating available custom roles before assigning one to a newly invited user

Auditing role names and IDs as part of an access management review

Retrieving role_id values to then call GET /authz2/v1/roles/{role_id}/scopes to inspect what each role permits

Best Practices

Cache role IDs in automation Workflows rather than calling this endpoint on every user assignment — custom roles change infrequently

Use role description fields consistently when creating roles to make this list actionable during audits

Cross-reference role assignments against GET /user/ to identify users assigned to each custom role

Workflow

Call GET /authz2/v1/roles/ to retrieve all custom roles and their IDs

Identify the target role by name or description

Call GET /authz2/v1/roles/{role_id}/scopes with the role's id to inspect its permission set

Use the role id in user assignments (PUT /authz2/v1/users/{user_id}) as needed