Guides

Authentication and keys

Every request carries an API key. A key belongs to one account, holds only the scopes it was given, and is shown once.

Send the key as a bearer token

Put the key in the Authorization header of every request, over HTTPS. Keys look like rai_live_<prefix>_<secret>; the prefix is what the console and the audit log show. The key decides the account, so there is no account id to pass.

Any request
curl https://api.rykon.ai/v1/tenant \
  -H "Authorization: Bearer $RYKON_AI_KEY"

A request with no key, or a key that is revoked, expired or not valid, is answered 401 before anything else happens, and the attempt is recorded:

401 Unauthorized
{
  "error": "unauthorized",
  "message": "authentication required",
  "requestId": "req-1a"
}

Make a key

  1. Sign in to the console and open API keys. Owners and admins can make and revoke keys.
  2. Name it after the system that will use it, so you know what breaks when you revoke it.
  3. Choose its scopes: the least that system needs. A key may hold only scopes you hold yourself.
  4. Optionally give it an expiry, from 1 to 365 days.
  5. Copy the key. It is shown once and cannot be shown again: we store only its hash.

A key is a password for your account

Keep it in your server's environment or a secret manager. Never put it in a browser, a mobile app or a repository. If a key is exposed or lost, revoke it; its very next request is refused, because keys are read on every request and never cached.

Scopes

A key can do only what its scopes allow. A call outside them is answered 403 forbidden, naming the missing scope:

403 Forbidden
{
  "error": "forbidden",
  "message": "this key does not hold agents:write",
  "detail": { "key": "k7m2q9xd", "required": "agents:write" },
  "requestId": "req-2b"
}
ScopeAllowsRoutes
tenant:readRead the account: name, plan, status and isolation.3
tenant:writeRename or close the account. Owners only.3
tenant:exportDownload everything the account holds as one archive. Owners and admins; never over MCP.1
members:readSee who is on the account and their roles.2
members:writeChange roles and remove people, within the caller’s own reach.2
keys:readList and open the account’s keys (never their secrets).2
keys:writeMake, change and revoke keys; a key gains only scopes the caller holds.3
audit:readRead the audit log.1
runs:readRead runs, their transcripts and their tool calls.4
runs:writeStart and stop runs.2
agents:readRead agents and the tool catalogue.3
agents:writeCreate, change and archive agents, at the default level.3
agents:autonomySet an agent’s autonomy level above L0. Owners and admins.0
approvals:readRead approvals, waiting and decided.2
approvals:writeEdit, approve and reject; honoured only for a person in the console.3
record:readRead the record of what agents did.1
killswitches:readSee kill switches.1
killswitches:writeEngage a kill switch on a run, an agent or the account.1
killswitches:releaseRelease a kill switch. Owners and admins.1
spend:readRead the month’s spend, the budget and whether the company is paused.2
spend:pauseLower spend: pause the company or a team, or switch to Quiet. Owners and admins; allowed over MCP.0
spend:writeRaise spend: resume, go back to Active, set budgets. Owners and admins; never over MCP.2
isolation:writeChange the run isolation policy: Standard or Strict, for the account and per role. Owners and admins; never over MCP.1
webhooks:readSee webhooks, their deliveries with every attempt, and triggers (never their secrets).5
webhooks:writeAdd, change, test, rotate and remove webhooks and triggers, and send a delivery again. Owners and admins; never over MCP.10

What each role can grant

A key holds at most the scopes of the person who made it, and it belongs to them: when they leave the account, their keys are revoked in the same step. This is what each role holds.

Scopeowneradminmemberviewer
tenant:read●●●●
tenant:write●···
tenant:export●●··
members:read●●●●
members:write●●··
keys:read●●··
keys:write●●··
audit:read●●··
runs:read●●●●
runs:write●●●·
agents:read●●●●
agents:write●●●·
agents:autonomy●●··
approvals:read●●●●
approvals:write●●●·
record:read●●●●
killswitches:read●●●●
killswitches:write●●●·
killswitches:release●●··
spend:read●●●●
spend:pause●●··
spend:write●●··
isolation:write●●··
webhooks:read●●●·
webhooks:write●●··

What no key can do

  • Decide an approval. Editing, approving and rejecting an agent's action is a person's act in the console. A key holding approvals:write is still refused 403. See Levels and approvals.
  • Reach another account. An id from another account answers 404, exactly like one that does not exist, and the attempt is recorded.
  • Climb. A key cannot make a key with a scope it does not hold, and no key can hold an operator scope.

Good practice

  • One key per system, so either can be revoked without touching the other.
  • Scopes as narrow as the job. A dashboard that reads runs holds runs:read and nothing else.
  • Call the API from your server. Your frontend asks your backend, and your backend holds the key.
  • Rotate by overlap: make the new key, deploy it, then revoke the old one.