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

Update a custom role

Changes a custom role's name, description, permissions, or its model, endpoint and network conditions, and returns it. Built-in roles cannot be changed. Requires a signed-in session. The same no-escalation rule as creation applies.

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 update <role-id>
PATCH
/v1/roles/{roleId}

Authorization

apiKey
headerAuthorizationBearer <token>

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

Path Parameters

roleId*string

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

Updated

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 PATCH 'https://api.openrelay.inc/v1/roles/string' \  -H 'Content-Type: application/json' \  -d '{}'
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"}

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.

Delete a custom role DELETE

Deletes one of the organization's custom roles and returns 204. A role still held by a member or service account is refused with 409 ROLE_IN_USE. Requires a signed-in session.