Authentication

The OpenRelay API authenticates requests with an API key. Each key is bound to a single organization, and what it may do is set by its owner's role and its own restrictions (Permissions), or by its scopes in an organization that has not enabled permissions yet. Send it as a bearer token on every request:

curl https://api.openrelay.inc/v1/me \
  -H "Authorization: Bearer or_your_api_key"

New API keys are prefixed with or_; keys issued earlier start with vl_ and still work. Treat them like passwords.

Create an API keyCopy Anchor Link

curl -X POST https://api.openrelay.inc/v1/orgs/{orgId}/api-keys/create \
  -H "Authorization: Bearer or_existing_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-pipeline" }'

{
  "id": "key_…",
  "name": "ci-pipeline",
  "key": "or_…",          // plaintext: shown once
  "keyPrefix": "or_abc12",
  "organizationId": "b3f9…"
}

Using your keyCopy Anchor Link

Pass the key in the Authorization header as Bearer or_… on every request. Requests without a valid key receive 401 Unauthorized; a key that lacks the required scope (or targets another org) receives 403 Forbidden.

export OPENRELAY_API_KEY="or_your_api_key"

curl https://api.openrelay.inc/v1/orgs/$ORG_ID/vms \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

Find your organization idCopy Anchor Link

Org-scoped endpoints take your organization id in the path (/v1/orgs/{orgId}/...). Every API key belongs to exactly one organization, so the id is never ambiguous. Three ways to get it:

1. Dashboard. Settings shows Organization ID under API access with a copy button. It is also shown in the reveal dialog when you create a key, and returned as organizationId in the create-key response.

2. API. Call GET /v1/whoami with any valid key. It requires no scopes and works for every or_ key:

   Copy Text

   curl https://api.openrelay.inc/v1/whoami \
     -H "Authorization: Bearer $OPENRELAY_API_KEY"

   Copy Text

   {
     "principalType": "api_key",
     "organizationId": "b3f9c2a1-8d4e-4f6a-9c0b-2e7d5a1f3b8c",
     "organizationName": "Acme",
     "scopes": ["clusters:read", "clusters:write"]
   }

3. CLI. orl account whoami prints the same information for the key you logged in with.

The organization id is an identifier, not a secret. It is safe to put in scripts, config files, and support requests.

Legacy scopesCopy Anchor Link

In an organization that has not enabled permissions, and for keys created before it did, two scopes decide what a key can do on the control-plane API:

A read-only key gets clusters:read. A key that manages VMs gets clusters:read and clusters:write. The dashboard offers these two as Read only and Read & write.

In an organization with permissions enabled, an API key can revoke only itself.

vms:read and vms:write are accepted for compatibility but grant nothing on their own: VM access comes from the clusters:* scopes. Creating a key with vms:write but not clusters:write (or vms:read but not clusters:read) returns 400.

Scopes do not gate the inference API: every active key in the organization can call it and spend the organization's balance, whatever its scopes. The inference scope is accepted but changes nothing today. The one inference restriction is inference:endpoint:<id>: a key carrying one or more of these can call only the listed dedicated endpoints, and any other model returns 404. It narrows that key; it does not stop other keys in the organization from calling the endpoint.

A control-plane request that exceeds a key's scopes returns 403. Check a key's scopes with GET /v1/whoami before debugging further.

Once your organization enables permissions, these keys keep their scopes, with four changes: they can no longer create keys (only a signed-in session can), an inference:endpoint:<id> key gets 403 model_not_allowed for other models instead of 404, your organization's guardrails and policies apply to them, and their restrictions cannot be edited. Each key keeps the restrictions it was created with; replace it to change them. A key created from then on is an organization key. A request that sends scopes gets an organization key whose ceiling matches them (Permissions).

Rotating and revokingCopy Anchor Link

• Rotate by creating a new key, deploying it, then revoking the old one.
• Revoke instantly with DELETE /v1/orgs/{orgId}/api-keys/{id} or from the dashboard. Revocation takes effect within seconds.