/Authentication & API keys
For Developers

Authentication & API keys

How OpenHelm API keys work, and how to keep them safe.

Every /v1 request authenticates with a Bearer API key.

Authorization: Bearer oh_live_...

Keys

  • Mint, name, and revoke keys under Settings → API & Webhooks (org owners/admins).
  • Keys are org-scoped. The full secret is shown once; OpenHelm stores only its SHA-256 hash.
  • oh_live_… runs against your real plan; oh_test_… is for test wiring.
  • Each key carries a webhook signing secret used to verify completion webhooks.

Guardrails on a key

  • Monthly cap — set monthly_cap_usd per key; spend beyond it returns 402.
  • Project allowlist — scope a key to specific projects.

The MCP servers reuse your key

When you connect an MCP server, the "Connect with OpenHelm" OAuth flow wraps your encrypted key in a signed token. The servers are stateless and store no secrets.

Errors

HTTP 4xx/5xx is reserved for request, auth, and quota problems (401 invalid key, 402 quota/subscription gate, 403 out-of-scope, 429 too many concurrent runs). A task that fails returns 200/202 with a structured failure_reason — see Runs & the result envelope.