Authentication
Authenticate every request with an API key.
The API authenticates with an API key sent as a Bearer token. There are no other auth methods - the key both identifies your workspace and authorizes the request.
The header
Send your key in the Authorization header on every request:
Authorization: Bearer ohk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKeys look like ohk_live_… (or ohk_test_… for a test key, whose calls are simulated). Create and manage them in the console under Account → API keys (owner or admin). The secret is shown once at creation - store it in a secret manager or environment variable, never in client code or a repo.
The workspace is implicit
A key belongs to exactly one workspace. That workspace is inferred from the key, so you never pass a workspace or tenant id - it never appears in any request or response body. To act on a different workspace, use a key created in that workspace.
Scopes
Every key is granted a set of scopes - the specific actions it may perform (calls:write, agents:read, and so on). Each endpoint requires exactly one scope; a key missing it gets a 403. Grant each key the narrowest set of scopes for its job. See the Scopes reference.
Failure responses
| Situation | Response |
|---|---|
No Authorization: Bearer header, or the token doesn’t start with ohk_live_ or ohk_test_ |
401 { "error": "unauthorized: missing or invalid API key" } |
| Unknown, revoked, or expired key | 401 { "error": "unauthorized: unknown, revoked, or expired API key" } |
| Valid key, but missing the endpoint’s scope | 403 { "error": "forbidden: API key is missing the '<scope>' scope" } |
Rotate & revoke
- Rotate a key from Account → API keys: you get a new key with the same permissions (shown once), and the old key keeps working for 24 hours so you can switch your integration over without downtime. Then it stops.
- Revoke a key if it’s exposed - it stops working immediately.
- Expiry: when you create a key you can give it a lifetime (30 days, 90 days, or a year). After that it stops working (
401). Keys without one never expire. - A workspace can hold up to 50 active keys.
Creating, rotating, and revoking keys are recorded in your workspace’s audit log. Each key’s usage is metered per request (requests the API served - refused ones don’t count), so you can track and attribute consumption.
Next: Errors →