Authentication

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_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys look like ohk_live_…. 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_	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

If a key is exposed, revoke it in the console (effective immediately) and create a new one. Rotate keys periodically. Each key’s usage is metered per request, so you can track and attribute consumption.

Next: Errors →