---
title: "List Roles API"
method: GET
path: "/authz2/v1/roles/"
tags: ["esper_cloud_api_Roles"]
---

# List Roles API

`GET /authz2/v1/roles/`

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 **Workflow**s 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

## Response `200`

Request Succeded

- object
  - `count` integer
  - `roles` EsperCloudApiRoleResponse[]
    - `id` string
    - `name` string
    - `description` string
    - `role_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/revisions/e1f64cbb488e/schema)