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 accessAPI Keys

Edit an API key budget

Sets, changes or removes an API key's spend budget and returns the key with its current spend. A limitNanoUsd of 0 removes the budget. Requires a signed-in session: your own key, or apikeys.write for any key. In organizations with permissions enabled, only the budget can be edited. Name, note and restrictions return 400. Available with permissions enabled; otherwise 404.

Required permission

Checked against the apikey.update permission for the resource it acts on. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

orl api-keys update <id>
PATCH
/v1/orgs/{orgId}/api-keys/{id}

Authorization

apiKey
headerAuthorizationBearer <token>

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

Path Parameters

orgId*string
id*string

Request Body

application/json
  1. body
name?stringDeprecated
Lengthlength <= 128
note?stringDeprecated
Lengthlength <= 512
restrictions?Deprecated

Refused with 400 in orgs with permissions enabled. Create a new key and revoke this one.

budget?

A change to the key's spend budget. A field left out keeps its value, so a key without a budget needs limitNanoUsd; a limitNanoUsd of 0 removes the budget. A new limit on the same period keeps the spend counted so far in the period; a new period, or a budget on a key that had none, counts from the update.

Response Body

Updated

application/json
  1. response
id*string
name*string
keyPrefix*string
scopes*array<string>
lastUsedAt?string
expiresAt?string
revokedAt?string
createdAt*string
kind?string

Absent for a key created before permissions (legacy).

Value in"personal""service""org""legacy"
ownerUserId?string

A personal key's owner.

serviceAccountId?string

A service key's account.

restrictions?
note?string

Where the key is used.

createdBy?string
budget?

The key's spend budget and what the key has spent in the current period. Amounts are integer nanoUSD (1 USD = 1,000,000,000). Every inference request the key makes counts, batches included, at the price it is billed, from when the budget was set; compute (VMs and pods) is not counted.

Example Request
curl -X PATCH 'https://api.openrelay.inc/v1/orgs/string/api-keys/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "name": "string",  "keyPrefix": "string",  "scopes": [    "string"  ],  "lastUsedAt": "string",  "expiresAt": "string",  "revokedAt": "string",  "createdAt": "string",  "kind": "personal",  "ownerUserId": "string",  "serviceAccountId": "string",  "restrictions": {    "permissions": [      "string"    ],    "models": [      "string"    ],    "endpoints": [      "string"    ],    "ipRanges": [      "string"    ]  },  "note": "string",  "createdBy": "string",  "budget": {    "limitNanoUsd": 0,    "period": "lifetime",    "spentNanoUsd": 0,    "periodEndsAt": "2019-08-24T14:15:22Z"  }}

Create an API key (returns the plaintext once) POST

Returns the new key's plaintext secret, which is shown only in this response, with its id, prefix, organization id, and any permissions or budget. With permissions enabled, only a signed-in session creates keys, and a new key belongs to the organization (kind org), so it keeps working if its creator leaves; personal and service kinds are refused, except dashboard playground keys, which are always personal. Its permissions come from template or permissions and can never exceed the creator's own access (403 ESCALATION_REFUSED). scopes still works and maps to the key's ceiling. budget caps what the new key may spend on inference per period. A key that carries a budget cannot create keys (403 FORBIDDEN), so it cannot mint itself one without a budget.

Revoke an API key DELETE

Revokes an API key in the organization, after which requests made with it no longer authenticate. With permissions enabled an unknown key id returns 404.