---
title: "List built-in and custom roles"
method: GET
path: "/v1/roles"
tags: ["Roles"]
---

# List built-in and custom roles

`GET /v1/roles`

## Request

- Base URL: `https://api.openrelay.inc`
- URL: `https://api.openrelay.inc/v1/roles`
- Auth: HTTP bearer

Returns the built-in roles and the organization's custom roles, each with its permission ids and how many members hold it.
The retired inference role is listed only while someone still holds it.

Requires the `role.read` permission. See [Permissions](https://docs.openrelay.inc/docs/permissions) for the roles and API key permissions that include it.

## Response `200`

Roles

- Role[]
  - `builtin` boolean, required
  - `cedar` string: The Cedar policies generated for the role (custom roles only).
  - `createdAt` string
  - `createdBy` string
  - `description` string
  - `endpoints` string[]: Dedicated endpoints every holder of the role is limited to.
  - `id` string, required: A built-in role id (owner, admin, member, billing, inference, viewer) or a custom role id (role_...).
  - `ipRanges` string[]: Networks every holder of the role is limited to.
  - `memberCount` integer
  - `models` string[]: Models every holder of the role is limited to.
  - `name` string, required
  - `permissions` string[], required
  - `stale` string: Set when the role names a permission this version of OpenRelay does not know, or no longer compiles: what it does now and what to change. The rest of the role still applies.
  - `updatedAt` string
  - `updatedBy` string

## Other responses

- `401`: Missing or invalid API key
- `403`: The caller is authenticated but may not do this. The caller's role or the API key's permissions do not allow it, or the request targets another organization (FORBIDDEN, or NOT_A_MEMBER for a session); a permission denial also names the action it needed (permission), which kind of policy denied it (deniedBy) and the deciding policy ids (policies). Or the organization is suspended pending review (ORG_SUSPENDED) or has been deleted (ORG_DISABLED). A new API key or a wider scope clears neither of the last two; see [Account and balance refusals](https://docs.openrelay.inc/docs/errors#account-and-balance-refusals). A user session whose email address is not confirmed is refused on every operation (EMAIL_UNVERIFIED); confirm the address from the confirmation email, then sign in again.
- `404`: Resource not found

## Changes

- **2026-10-26** `7fe59d94a9f5`: 3 info
  - added the optional property `requestId` to the response with the `401` status
  - added the optional property `requestId` to the response with the `403` status
  - added the optional property `requestId` to the response with the `404` status
- **2026-10-22** `551a288b9aa0`: 1 warning
  - removed the optional property `items/serviceAccountCount` from the response with the `200` status
- **2026-10-10** `12b2fcbcc298`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openrelay/apis/openrelay-api/changes/v1/roles/get.md)

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) - [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openrelay/apis/openrelay-api/revisions/7fe59d94a9f5?raw)