API Access
Scope
Full control and scoped keys, every scope, and the endpoints each one covers.
A scope is a permission on an API key to use a group of endpoints, such as sending inference requests or changing routers. A key either has full control, with no restriction, or a set of scopes that names exactly what it can do. Scopes are chosen in the Access editor when a key is created, and changed later with Access on the key's row.
Full control and scoped keys
The Access editor sets a key to one of two modes:
| Mode | Dashboard label | Key can |
|---|---|---|
| Full control | Full control | Use every endpoint the organization can, including endpoints added to the API later. |
| Scoped | Scoped | Use only the endpoints its scopes name. Endpoints added later stay closed until a scope for them is granted. |
A scoped key with an empty set shows as No access in the list. Scoped keys suit applications: a key that holds only inference keeps routers and prompts safe from change if it leaks.
Data plane scopes
Data plane scopes cover sending requests to models and listing them:
| Scope | Dashboard row | Endpoint |
|---|---|---|
inference | Inference | POST /v1/chat/completions |
inference | Inference | POST /v1/messages |
inference | Inference | POST /v1/messages/count_tokens |
inference | Inference | POST /v1/responses |
inference | Inference | The Claude Proxy Bedrock endpoints under /bedrock |
inference | Inference | The Claude Proxy Vertex endpoints under /vertex |
inference | Inference | The Gemini Proxy endpoints under /v1beta/models |
models:read | Model catalog | GET /v1/models |
The Inference row offers None, Any router, or Specific routers, which limits the key to a list of routers. See Router Access.
Control plane scopes
Control plane scopes cover managing resources through the API. Each resource group has levels that build on each other: read allows reading, write adds creating and changing, and delete adds deleting. A key holds one level per group. Reading uses GET, writing uses POST and PATCH, and deleting uses DELETE.
| Scope | Dashboard row | Level | Allows |
|---|---|---|---|
routers:read | Routers | Read | Reading on /v1/routers |
routers:write | Routers | Write | Reading, creating and changing on /v1/routers |
routers:delete | Routers | Delete | Reading, creating, changing and deleting on /v1/routers |
prompts:read | Prompts | Read | Reading on /v1/prompts |
prompts:write | Prompts | Write | Reading, creating and changing on /v1/prompts |
prompts:delete | Prompts | Delete | Reading, creating, changing and deleting on /v1/prompts |
prompt_repos:read | Prompt repos | Read | Reading on /v1/prompt-repos |
prompt_repos:write | Prompt repos | Write | Reading, creating and changing on /v1/prompt-repos |
prompt_repos:delete | Prompt repos | Delete | Reading, creating, changing and deleting on /v1/prompt-repos |
github:read | GitHub | Read | Reading on /v1/github/connections |
github:delete | GitHub | Delete | Reading and deleting on /v1/github/connections |
provider_keys:read | Provider keys | Read | Reading on /v1/provider-keys |
provider_keys:write | Provider keys | Write | Reading, creating and changing on /v1/provider-keys |
provider_keys:delete | Provider keys | Delete | Reading, creating, changing and deleting on /v1/provider-keys |
integrations:read | Not shown | Read | Reading on /v1/integration-types, /v1/integrations and /v1/routers/{id}/integrations |
integrations:write | Not shown | Write | Reading, creating, changing, testing and deleting on /v1/integrations, and attaching, changing, ordering and detaching on /v1/routers/{id}/integrations |
model_groups:read | Model groups | Read | Reading on /v1/model-groups |
model_groups:write | Model groups | Write | Reading, creating and changing on /v1/model-groups |
model_groups:delete | Model groups | Delete | Reading, creating, changing and deleting on /v1/model-groups |
budgets:read | Budgets | Read | Reading on /v1/budgets |
budgets:write | Budgets | Write | Reading, creating and changing on /v1/budgets |
budgets:delete | Budgets | Delete | Reading, creating, changing and deleting on /v1/budgets |
traffic:read | Traffic | Read | Reading on /v1/traffic |
traffic:reveal | Traffic originals | Reveal | reveal=true on GET /v1/traffic/requests/{request_id}/payload, with traffic:read |
tags:read | Tags | Read | Reading on /v1/tags |
api_tokens:read | API tokens | Read | Reading on /v1/api-tokens |
agents:read | Agents | Read | Reading on /v1/agents |
agents:delete | Agents | Delete | Reading and deleting on /v1/agents |
organizations:read | Organizations | Read | Reading on /v1/organizations |
organizations:write | Organizations | Write | Reading, creating and changing on /v1/organizations |
organizations:delete | Organizations | Delete | Reading, creating, changing and deleting on /v1/organizations |
invites:read | Invites | Read | Reading on /v1/people/invites |
invites:write | Invites | Write | Reading, creating and changing on /v1/people/invites |
invites:delete | Invites | Delete | Reading, creating, changing and deleting on /v1/people/invites |
sso:read | SSO | Read | Reading on /v1/sso |
sso:write | SSO | Write | Reading, creating and changing on /v1/sso |
sso:delete | SSO | Delete | Reading, creating, changing and deleting on /v1/sso |
machine_identity:read | Machine identity | Read | Reading on /v1/machine-identity |
machine_identity:write | Machine identity | Write | Reading, creating and changing on /v1/machine-identity |
machine_identity:delete | Machine identity | Delete | Reading, creating, changing and deleting on /v1/machine-identity |
GitHub connections and agents are read and removed through the API, and set up in the dashboard and the Portal, so those groups have no write level. Integrations have read and write levels, and deleting an integration or detaching it from a router needs write. The Access editor has no Integrations row, so full control keys reach the integrations endpoints. traffic:reveal is separate from the Traffic levels, and only an organization admin can grant it. Traffic, tags and API tokens are read-only through the API. Three GET endpoints need budgets:write: a budget's overrides, its budget requests and one budget request. The catalog endpoints under /v1/catalog need models:read.
Presets
Presets set every row of the Access editor at once:
| Preset | Scopes |
|---|---|
| Inference only | inference on any router, and models:read. New keys start with this preset. |
| Read everything | inference, models:read, and Read on every control plane row. |
| Nothing | An empty set of scopes. |
When every group is set to its highest level, the editor notes that the key still holds a fixed list, and offers Switch to Full control for a key that should also reach endpoints added later.
Examples
Common keys and the access each needs:
| Key for | Access |
|---|---|
| A production application | Inference only, with a router list naming the routers it calls. |
| A script that audits router and prompt configuration | Read on Routers, Prompts and Model groups, with Inference set to None. |
| A deployment pipeline that manages routers and prompts | Routers, Prompts and Model groups at Write or Delete, with Inference set to None. |
| Claude Desktop | inference and models:read, limited to its Claude Proxy. |
Scope names
Each scope has a name, such as routers:write, which error messages use to say which scope a request needs. A key holds one level per group, and each level includes the ones below it, so a key with routers:write also reads routers. Workloads that sign in with Machine Identity hold inference. See Machine Identity.
Errors
A scoped key that calls an endpoint outside its scopes receives one of these responses:
| Status | Response | Cause |
|---|---|---|
| 403 | insufficient_scope, with the message this API key is not permitted to use this endpoint; it requires the <scope> scope | The endpoint needs a scope the key lacks. The message names the lowest scope that allows the request. |
| 403 | insufficient_scope, with the message this API key is not permitted to use this endpoint | The endpoint belongs to no scope the key can hold, such as a newer endpoint. |
| 403 | API token lacks the required inference scope | A Bedrock or Vertex request through a Claude Proxy, from a key without inference. |
| 404 | not found | The method is not one the group offers, such as a write to provider keys. |