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 accessService Accounts

Create a service account

Creates an organization-owned identity with a role, for API keys not tied to a person. It cannot hold the Owner role; an org may have at most 200. Requires a signed-in session. Its role must be within the creator's own access.

Required permission

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

Command line

The orl CLI wraps this endpoint:

orl service-accounts create --name <name> --role-id <role-id>
POST
/v1/service-accounts

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
roleId*string

Response Body

Created

application/json
  1. response
id*string
name*string
description?string
roleId*string
roleName?string
disabled*boolean

A disabled account's keys are denied every request.

keyCount*integer

Live keys the account holds.

createdBy*string
createdAt*string
Example Request
curl -X POST 'https://api.openrelay.inc/v1/service-accounts' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "roleId": "string"}'
Example Response
{  "id": "string",  "name": "string",  "description": "string",  "roleId": "string",  "roleName": "string",  "disabled": true,  "keyCount": 0,  "createdBy": "string",  "createdAt": "string"}

List service accounts GET

Returns the organization's service accounts, each with its role, whether it is disabled, how many unrevoked API keys it holds, and who created it.

Get a service account GET

Returns one service account by id: its name, description, role, whether it is disabled, how many unrevoked API keys it holds, and who created it and when.