Manage

Capabilities & key scopes

What a project API key is allowed to do — the capability model behind every public endpoint, and how grants are assigned.

Granting capabilities

Grant capabilities in the dashboard: Project → API Keys → edit a key. Keys with Restricted permissions show a Capabilities checklist covering every explicit grant below — provisioning (buckets, agents), ingestion (web pages), and the destructive deletes. "All models" keys carry every capability implicitly.

Two capabilities are not in the checklist because they are granted automatically: knowledge:file:create and knowledge:file:read ride the key's knowledge-API access — any key with the knowledge file API enabled carries both, which is why a plain restricted sync key can upload and poll files without any checklist grants. Grants take effect on the key's next request.

How authorization works

Every project API key carries a set of capabilities. Each capability-protected endpoint (the ingest and manage surfaces) requires one; a key without it receives 403 forbidden_project_key, and the error names exactly what was missing:

{
  "error": {
    "code": "forbidden_project_key",
    "message": "This API key lacks the required capability.",
    "retryable": false,
    "details": { "required_capability": "knowledge:website:create" }
  },
  "request_id": "req_abc123"
}

Capability catalog

Capability	Grants	Required by
`knowledge:file:read`	Read sources, buckets, tasks, batches	`GET /v1/sources/{id}`, `GET /v1/buckets`, status endpoints
`knowledge:file:create`	Ingest files	Uploads, upload sessions, batches, `files/import`
`knowledge:file:delete`	Remove individual sources	`DELETE /v1/sources/{id}`, bucket detachment (`DELETE /v1/buckets/{bucket}/sources/{id}`, `files:remove`)
`knowledge:website:create`	Ingest web pages	`POST /v1/buckets/{bucket}/pages` (and `/websites`)
`knowledge:bucket:create`	Provision buckets	`POST /v1/buckets`, `PUT /v1/buckets/{slug}`
`knowledge:bucket:delete`	Delete a bucket and its member files — this single grant authorizes the whole cascade; `knowledge:file:delete` is not additionally required	`DELETE /v1/buckets/{bucket}?force=true`
`rag:agent:create`	Provision agents	`POST /v1/agents` (alias: `POST /v1/rag-agent/agents`)
`rag:agent:delete`	Delete a named agent	`DELETE /v1/agents/{agent_id}`
`rag:agent:update`	Update a named agent	`PUT /v1/agents/{agent_id}`

The ask and search surfaces (/v1/responses, /v1/chat/completions, /v1/search, /v1/models) authenticate with the key itself and are governed by your plan's answer entitlements rather than per-capability grants.

How grants are assigned

Full-access keys (type: all) carry every capability.
Restricted keys carry an explicit capability list — scope them to what the integration actually does.
Keys with the knowledge file API enabled automatically carry knowledge:file:create and knowledge:file:read. Nothing else is implied: provisioning capabilities (knowledge:bucket:create, rag:agent:create) and destructive ones (knowledge:file:delete, knowledge:bucket:delete, rag:agent:delete) must be granted deliberately.
knowledge:website:create is explicit-only by design — page ingestion runs third-party crawling and analysis per call, so it never rides an implicit grant.

Practical guidance

Give a sync job knowledge:file:create + knowledge:file:read and nothing else.
Give a provisioning script knowledge:bucket:create (and rag:agent:create if it creates agents), and run it separately from steady-state ingestion.
Rotate any key that has more capability than its integration uses.

Next steps

Agents

MCP Server