スコープリファレンス

API key scopes は resource-and-verb grants です。すべての public OpenAPI operation が required scope、risk class、route ID を公開します。

Grant model

Concrete scopes は feature:verb 形式です。VoiceAgent support が明示的に承認しない限り、partner keys には concrete scopes を使用してください。

read は list と detail operations を許可します。
write は create、update、import、release、delete を許可します。
execute は cost-bearing または side-effecting operations を許可します。
admin は workspace deletion などの governance operations を許可します。

Wildcard behavior

agents:* のような feature wildcard は valid grants ですが、 admin-managed bundles 向けです。Super wildcard * と input alias *:* は legacy/admin-only compatibility grants であり、新しい 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

各 operation は openapi.yaml で x-api-key-required-scope、x-api-key-risk-class、 x-route-id を公開します。403 scope failure は SCOPE_INSUFFICIENT envelope を返し、details.requiredScope と details.routeId を含みます。

High-risk scopes は key creation 時に明示的に選択し、automated partner systems に付与する前に review してください。