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.
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:
{
"error": "unauthorized",
"message": "authentication required",
"requestId": "req-1a"
}Make a key
- Sign in to the console and open API keys. Owners and admins can make and revoke keys.
- Name it after the system that will use it, so you know what breaks when you revoke it.
- Choose its scopes: the least that system needs. A key may hold only scopes you hold yourself.
- Optionally give it an expiry, from 1 to 365 days.
- 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
Scopes
A key can do only what its scopes allow. A call outside them is answered 403 forbidden, naming the missing scope:
{
"error": "forbidden",
"message": "this key does not hold agents:write",
"detail": { "key": "k7m2q9xd", "required": "agents:write" },
"requestId": "req-2b"
}| Scope | Allows | Routes |
|---|---|---|
| tenant:read | Read the account: name, plan, status and isolation. | 3 |
| tenant:write | Rename or close the account. Owners only. | 3 |
| tenant:export | Download everything the account holds as one archive. Owners and admins; never over MCP. | 1 |
| members:read | See who is on the account and their roles. | 2 |
| members:write | Change roles and remove people, within the caller’s own reach. | 2 |
| keys:read | List and open the account’s keys (never their secrets). | 2 |
| keys:write | Make, change and revoke keys; a key gains only scopes the caller holds. | 3 |
| audit:read | Read the audit log. | 1 |
| runs:read | Read runs, their transcripts and their tool calls. | 4 |
| runs:write | Start and stop runs. | 2 |
| agents:read | Read agents and the tool catalogue. | 3 |
| agents:write | Create, change and archive agents, at the default level. | 3 |
| agents:autonomy | Set an agent’s autonomy level above L0. Owners and admins. | 0 |
| approvals:read | Read approvals, waiting and decided. | 2 |
| approvals:write | Edit, approve and reject; honoured only for a person in the console. | 3 |
| record:read | Read the record of what agents did. | 1 |
| killswitches:read | See kill switches. | 1 |
| killswitches:write | Engage a kill switch on a run, an agent or the account. | 1 |
| killswitches:release | Release a kill switch. Owners and admins. | 1 |
| spend:read | Read the month’s spend, the budget and whether the company is paused. | 2 |
| spend:pause | Lower spend: pause the company or a team, or switch to Quiet. Owners and admins; allowed over MCP. | 0 |
| spend:write | Raise spend: resume, go back to Active, set budgets. Owners and admins; never over MCP. | 2 |
| isolation:write | Change the run isolation policy: Standard or Strict, for the account and per role. Owners and admins; never over MCP. | 1 |
| webhooks:read | See webhooks, their deliveries with every attempt, and triggers (never their secrets). | 5 |
| webhooks:write | Add, 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.
| Scope | owner | admin | member | viewer |
|---|---|---|---|---|
| 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:writeis still refused403. 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:readand 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.