OpenRelay API Documentation

Authenticate every request with an OpenRelay API key (vl_…) sent as a Bearer token.

The OpenRelay API authenticates requests with an API key. Each key is bound to a single organization and carries a set of scopes. Send it as a bearer token on every request:

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

API keys are prefixed with vl_. Treat them like passwords.

The easy way: orl auth login

Using the orl CLI? Run orl auth login, paste the key once, and orl keeps it in your OS keyring and reads your organization from it. No headers to set. See CLI Authentication.

Keep keys secret

Never commit API keys to source control, embed them in client-side code, or share them in screenshots. Use environment variables or a secrets manager. If a key leaks, revoke it immediately and issue a new one.

Create an API key

From the dashboard

Go to Settings → API Keys in the dashboard, create a key, and copy it. The plaintext value is shown once — store it somewhere safe.

Or via the API

If you already have a key (or a session), you can mint more. The plaintext key is returned once in the response and never again:

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

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

The response includes organizationId, the org the key is bound to. Store it with the key: org-scoped endpoints take it in the path.

See Create an API key in the reference.

Using your key

Pass the key in the Authorization header as Bearer vl_… 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.

Set it once in your shell

export OPENRELAY_API_KEY="vl_your_api_key"

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

Find your organization id

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:

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.

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

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

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

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.

Scopes

Keys carry scopes such as clusters:read, vms:write, and billing:read. Grant a key only the scopes it needs — for example, a monitoring job that only reads usage should get read scopes, not write. A request that exceeds a key's scopes returns 403.

Rotating and revoking

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.

Two ways to authenticate

This reference documents API key auth (vl_…), which is what you'll use for automation and SDKs. The dashboard itself uses short-lived user session tokens — you don't need those to build on the API.

Authentication