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

Create a custom role

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.

Required permission

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

Command line

The orl CLI wraps this endpoint:

orl roles create --name <name> --permissions <permissions>
POST
/v1/roles

Authorization

apiKey
headerAuthorizationBearer <token>

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

Request Body

application/json
  1. body
name*string
Lengthlength <= 64
description?string
Lengthlength <= 256
permissions*array<string>
models?array<string>
endpoints?array<string>
ipRanges?array<string>

Response Body

Created

application/json
  1. response
id*string

A built-in role id (owner, admin, member, billing, inference, viewer) or a custom role id (role_...).

name*string
description?string
builtin*boolean
permissions*array<string>
models?array<string>

Models every holder of the role is limited to.

endpoints?array<string>

Dedicated endpoints every holder of the role is limited to.

ipRanges?array<string>

Networks every holder of the role is limited to.

memberCount?integer
serviceAccountCount?integer
cedar?string

The Cedar policies generated for the role (custom roles only).

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.

createdBy?string
createdAt?string
updatedBy?string
updatedAt?string
Example Request
curl -X POST 'https://api.openrelay.inc/v1/roles' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "permissions": [    "string"  ]}'
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"}

List built-in and custom roles GET

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.

Get a role, with its generated Cedar GET

Returns one built-in or custom role with its permission ids and holder counts. A custom role also carries its conditions and the Cedar generated from it.