Get a role, with its generated Cedar
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.
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 get <role-id>apiKeyAuthorizationBearer <token>OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).
roleId*stringThe role
application/json- response
id*stringA built-in role id (owner, admin, member, billing, inference, viewer) or a custom role id (role_...).
name*stringdescription?stringbuiltin*booleanpermissions*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?integerserviceAccountCount?integercedar?stringThe Cedar policies generated for the role (custom roles only).
stale?stringSet 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?stringcreatedAt?stringupdatedBy?stringupdatedAt?stringcurl -X GET 'https://api.openrelay.inc/v1/roles/string'{ "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"}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.
Update a custom role PATCH
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.