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.

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"
}

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"

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