Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
PricingDashboard
GuidesAPI ReferenceCLI
API ReferenceAccount and accessRoles

List built-in and custom roles

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

Required permission

Requires the role.read permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

orl roles list
GET
/v1/roles

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Response Body

Roles

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://api.openrelay.inc/v1/roles'
Example Response
[  {    "id": "string",    "name": "string",    "description": "string",    "builtin": true,    "permissions": [      "string"    ],    "models": [      "string"    ],    "endpoints": [      "string"    ],    "ipRanges": [      "string"    ],    "memberCount": 0,    "serviceAccountCount": 0,    "cedar": "string",    "stale": "string",    "createdBy": "string",    "createdAt": "string",    "updatedBy": "string",    "updatedAt": "string"  }]

Overview

Built-in and custom roles. A custom role is a set of permissions plus optional model, endpoint and network conditions. Available to organizations with permissions enabled; otherwise these endpoints return 404.

Create a custom role POST

Creates a custom role from a set of permissions plus optional model, endpoint and network conditions, and returns it. A role cannot grant more than you hold. Requires a signed-in session. A role that grants more than its creator holds is refused with 403 ESCALATION_REFUSED, which names the first missing permission.