The permissions an API key can carry, what each one unlocks, and how to choose them.

A scope is one permission on one kind of resource, written as resource:action. A key only reaches the endpoints its scopes allow; everything else answers 403. Every operation in the API reference lists the scope it requires.

The scopes

Scope	Grants
`agency-usage:read`	Read the monthly run, token and cost totals of the clients you manage. Read-only; reaches no other agency route.
`agents:read`	List and read agent configurations.
`agents:run`	Start agent runs and control them (stop, pause, resume, retry, answer a question).
`agents:write`	Create, edit, share, publish and delete agents.
`analytics:read`	Read usage analytics: activity and cost summary, per-agent stats, usage and spend per user, team, agent and model, plus the workspace balance, plan usage and monthly statement. Read-only; administrators see the whole workspace, team managers their own teams.
`approvals:read`	Read pending approval requests. Does NOT allow deciding them.
`chat:read`	Read chats, messages and history.
`chat:write`	Create chats and send/modify messages.
`knowledge:read`	Search and read knowledge bases and documents.
`knowledge:write`	Upload, modify or delete knowledge.
`runs:read`	Read run records and their details.
`runs:write`	Submit feedback on runs.
`tasks:read`	List and read board tasks.
`tasks:write`	Create, edit and delete board tasks.
`workflows:read`	List and read workflows, their graphs and run history.
`workflows:run`	Trigger workflow runs.
`workflows:write`	Create, edit, deploy and delete workflows.

Rules worth knowing

Write includes read. A key with tasks:write can also read tasks. You do not need to grant tasks:read separately.
Run does not include read or write. agents:run starts and controls runs. It cannot read an agent's configuration (agents:read) or change it (agents:write).
Running and editing are separate. Starting a run, stopping it, retrying it and answering an agent's question need agents:run. Creating, editing, sharing, publishing or deleting an agent needs agents:write. Workflows work the same way with workflows:run and workflows:write.
Approvals are read-only. approvals:read lists what is waiting. Deciding is always done by a person in the app.
Agency usage is for agencies. agency-usage:read exists only in agency workspaces.

Choose the smallest set

Give each integration its own key with only what it uses. Some common sets:

Integration	Scopes
Create tasks and let agents work on them	`tasks:write`, `agents:read`, `agents:run`, `runs:read`
Ask an agent a question from your product	`agents:run`
Chat completions	`chat:write`
Search knowledge from another app	`knowledge:read`
Reporting dashboard	`analytics:read`

You can change a key's scopes later with Edit scopes; see Authentication.

When a scope is missing

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key missing required scope 'agents:read'. Granted scopes: tasks:read.",
    "detail": { "code": "API_KEY_SCOPE_MISSING" }
  }
}

The message names the scope to add. See Rate limits and errors for every error code.

Scopes

The scopes

Rules worth knowing

Choose the smallest set

When a scope is missing