API Keys

API keys are the credential for the programmatic surface. They belong to a workspace and carry a list of scopes.

Create a key

curl -b cookies.txt -X POST https://api.runne.run/v1/workspaces/WORKSPACE_ID/api-keys \
  -H 'Content-Type: application/json' \
  -d '{"name":"prod-key","scopes":["chat:write","balance:read"]}'

Request body:

Field	Type	Required	Notes
name	string	yes	min 1 char
scopes	string[]	yes	min 1 element
rate_limit	object	no	{requests_per_minute, tokens_per_day} — both positive ints

If rate_limit is omitted, the defaults are requests_per_minute: 60 and tokens_per_day: 1000000.

Response (HTTP 201):

{
  "id": "0191…",
  "raw_key": "rn_live_4xK9mP2qR7sT_7hJ3kL9mN2pQ5rT8vW1xY4zA6bC0dE2fG4hI6jK8",
  "key_id": "4xK9mP2qR7sT",
  "name": "prod-key",
  "scopes": ["chat:write", "balance:read"],
  "created_at": "…"
}

List keys

curl -b cookies.txt https://api.runne.run/v1/workspaces/WORKSPACE_ID/api-keys

{
  "api_keys": [
    {
      "id": "0191…",
      "key_id": "4xK9mP2qR7sT",
      "name": "prod-key",
      "scopes": ["chat:write", "balance:read"],
      "created_at": "…",
      "last_used_at": "…",
      "revoked_at": null
    }
  ]
}

The raw secret is never present in the list response — only the public key_id.

Revoke a key

curl -b cookies.txt -X DELETE https://api.runne.run/v1/workspaces/WORKSPACE_ID/api-keys/API_KEY_ID

Response:

{ "success": true }

Revocation sets revoked_at. A revoked key is rejected by the gateway (401 invalid or revoked API key) on its next request. Revoking a non-existent or foreign key returns 404.

Scope matrix

A key only works on an endpoint if it carries the required scope. The table lists what the server actually enforces.

Endpoint	Required scope	Enforced?
POST /v1/chat/completions	chat:write	yes
GET /v1/balance	balance:read	yes
GET /v1/models	models:read	no — catalog is public

models:read is not enforced

GET /v1/models (and GET /v1/models/{provider}/{model}) currently require no authentication, so models:read is a reserved scope with no enforcement. Treat the catalog as public in beta.

Grant the minimum scopes a client needs. A key with only balance:read cannot call chat completions, and vice versa.

Raw-key security

raw_key is returned exactly once, at creation. The server stores only HMAC-SHA256(secret) and cannot reconstruct the raw value.

• Store the key in a secrets manager; never in source control or logs.
• Never print raw_key in logs or error messages.
• Rotate by revoking the old key and creating a new one (client-side rotation), or by rotating the server secrets (API_KEY_SERVER_SECRET / _PREV) for graceful server-side rotation — see Authentication.
• Regenerate rather than "recover": there is no "reveal raw key" endpoint by design.

Related

• Authentication — key format and verification.
• Rate Limits & Quotas — per-key rate limits.