Scope Reference

API key scopes use resource-and-verb grants. Every public OpenAPI operation declares its required scope, risk class, and route ID.

Grant Model

Concrete scopes use feature:verb. Use concrete scopes for partner keys unless VoiceAgent support explicitly approves a broader grant.

read grants list and detail operations.
write grants create, update, import, release, and delete operations.
execute grants cost-bearing or side-effecting test/run operations.
admin grants governance operations such as workspace deletion.

Wildcard Behavior

Feature wildcards such as agents:* are valid grants but are intended for admin-managed bundles. The super wildcard * and input alias *:* are legacy/admin-only compatibility grants and should not be requested for new partner integrations.

Scope Summary

Scope	Risk	Endpoints
`agents:read`	standard	9
`agents:write`	standard	9
`agents:admin`	standard	1
`agents:execute`	standard	1
`knowledge-bases:read`	standard	7
`knowledge-bases:write`	standard	8
`entity-indexes:read`	standard	5
`entity-indexes:write`	standard	8
`phone-numbers:read`	standard	2
`phone-numbers:write`	high	4
`calls:read`	standard	7
`calls:execute`	high	3
`analytics:read`	standard	1
`post-call-actions:read`	standard	6
`post-call-actions:write`	standard	4
`post-call-actions:execute`	high	2
`api-keys:read`	standard	1
`api-keys:write`	high	1
`api-keys:admin`	high	1
`workspace:read`	standard	4
`workspace:write`	standard	1
`workspace:admin`	high	4
`webhooks:read`	standard	2
`webhooks:write`	high	6
`webhooks:execute`	standard	2
`test-scenarios:read`	standard	5
`test-scenarios:write`	standard	4
`test-scenarios:execute`	standard	2

Endpoint Metadata

Each operation in openapi.yaml exposes x-api-key-required-scope, x-api-key-risk-class, and x-route-id. A 403 scope failure returns the canonical SCOPE_INSUFFICIENT envelope with details.requiredScope and details.routeId.

High-risk scopes should be selected explicitly during key creation and reviewed before granting to automated partner systems.