API reference

Authentication & API keys

Bearer keys, key hygiene, rotation, and revocation.

Bearer authentication

Every /api/v1/* endpoint expects an HTTP header:

Authorization: Bearer sk-runaii-<48 hex chars>

Keys are generated in Console → API Keys, shown once at creation, and stored hashed (HMAC-SHA256 with a server-side pepper) — nobody, including us, can read them from the database.

Key properties

Scoped to your account — a key can never see another account's usage or balance
Revocable instantly — revoking a key makes it fail on the very next request (hash lookup miss; no grace period)
Rate limited per key — 60 requests/min on the standard tier; over-limit calls get 429 with a Retry-After header
Per-key daily spend cap (optional) — set a cap at creation; over-cap calls get 402 even when the account balance is fine. Good for agent workloads.

Hygiene

One key per environment (dev / staging / prod) — rotate independently
Never ship keys in client-side code; the /api/v1/* surface is server-to-server
Rotated or leaked? Delete and re-mint in seconds — old keys die immediately
Check a key's status and balance any time:

curl https://api.runaii.cloud/v1/key -H "Authorization: Bearer sk-runaii-..."

{
  "data": { "label": "prod", "usage": 0.42, "rate_limit": { "requests": 60, "interval": "1m" } },
  "balance_credits": 8.74,
  "reserved_credits": 0.000042
}

reserved_credits is the in-flight estimate for requests currently executing.