Reference

Authentication

Every API call carries a workspace API key as a Bearer token. What the gateway checks and what it answers.

Send the key

Shell

curl -s "$DRUMS_URL/v1/health" -H "Authorization: Bearer $DRUMS_TOKEN"

DRUMS_URL and DRUMS_TOKEN are the two variables the quickstart exports. The SDK sends the same header from token= or $DRUMS_TOKEN. Requests go to https://beta.drums.run/gw, over HTTPS only.

Key format

Text

drums_sk_<prefix: 12 characters a-z, 2-7>_<secret: 43 characters base64url>

The prefix identifies the key in the console and the audit log; it is not a secret. The secret is 32 random bytes. Drums stores only the SHA-256 of the whole key.

What the gateway checks

On every request, before anything else:

The Authorization header holds Bearer <key> in exactly that format.
A key with that prefix exists and the hash matches (compared in constant time).
It is not revoked and not expired.
Its owner is still an active member of the workspace, and the workspace is active (not suspended).
The key's workspace is the one bound to this worker host.
The route's scope is among the key's effective scopes: the key's scopes intersected with the owner's current role.

Every failure in steps 1 to 4 is the same reply, so that nothing about which keys exist is revealed:

JSON

{
  "error": "missing, invalid, revoked or expired API key",
  "code": "unauthenticated",
  "request_id": "gw_01M6KSPP4JYWSQN6MEQM31SJVX"
}

with status 401 and WWW-Authenticate: Bearer realm="drums". A key without the route's scope gets 403 forbidden. Revocation takes effect on the next request: valid keys are never cached.

Scopes

Scope	Gateway routes that need it	Who can grant it
computers:read	GET /v1/tasks (or runs:read) GET /v1/tasks/{id} (or runs:read) GET /v1/checkpoints GET /v1/checkpoints/{id} GET /v1/slots GET /v1/slots/{id} GET /v1/slots/{id}/screenshot GET /v1/slots/{id}/gates GET /v1/slots/{id}/metrics	Any member
computers:write	POST /v1/metrics/reset DELETE /v1/checkpoints/{id} POST /v1/slots DELETE /v1/slots/{id} POST /v1/slots/{id}/reset POST /v1/slots/{id}/step POST /v1/slots/{id}/task POST /v1/slots/{id}/verify POST /v1/slots/{id}/quiescent POST /v1/slots/{id}/quarantine POST /v1/slots/{id}/release POST /v1/slots/{id}/capture POST /v1/slots/{id}/branch	Any member
runs:read	GET /v1/tasks (or computers:read) GET /v1/tasks/{id} (or computers:read) GET /v1/runs GET /v1/runs/{id}	Any member
runs:write	POST /v1/runs	Any member
templates:read	None in this version (no API-key route uses it yet)	Any member
templates:write	None in this version (no API-key route uses it yet)	Owners and admins
usage:read	GET /v1/metrics	Any member
audit:read	GET /v1/audit	Owners and admins

Members cannot put templates:write or audit:read on a key; owners and admins can. The routes column is generated from the gateway's own table. templates:read and templates:write have no API-key route in this version: templates are managed in the console. The API-key routes (/v1/api-keys) need no scope but an owner or admin key.

Failed attempts

Failed authentications are limited per source IP address (1 per second, burst 20) before any key lookup; over that, the gateway answers 429 rate_limited with Retry-After. A refused call with a known key (wrong secret, revoked, expired, owner removed) is recorded in the workspace's audit log as api_key.denied, at most once a minute per key.

Console sessions

The console (console.drums.run) uses a browser session, not API keys, and its /api/* routes accept only that session. API keys are for programs; sessions are for people.