Skip to main content
Every Public API key carries a list of operation scopes. Each endpoint requires one or more scopes; calls without the right scope return 403 Forbidden with { "error": { "code": "FORBIDDEN", "message": "API key does not have access to operation(s): <scopes>" } }.

​
Scope naming

Scopes use the form <resource>:<verb>. The available scopes today:
Endpoints addressed by a client and a site — linking and unlinking the two (PUT/DELETE /v1/client/{clientId}/site/{siteId}) and labelling the link (PUT/DELETE /v1/client/{clientId}/site/{siteId}/label/{labelId}) — touch both resources, so they require both client:write and site:write. Likewise, linking and unlinking a conversation and a site (PUT/DELETE /v1/conversation/{id}/site/{siteId}) require both conversation:write and site:write.
Projects endpoints need more than a scope. Every endpoint under /v1/project is available only to partners with access to ProVision Projects. A key with project:read or project:write that belongs to a partner without that access is rejected with 403 Forbidden and { "error": { "code": "FORBIDDEN", "message": "Partner does not have access to ProVision Projects" } }. Contact your OneVision representative to enable ProVision Projects.
Each endpoint’s required scope is also shown in the API Reference tab in the “Required permissions” callout under the endpoint summary.

​
Choosing scopes

When you create a key in Settings → Integrations → Developer (see Authentication), select the minimum set of scopes your integration needs. Granting a parent resource also grants its children (for example, client:read includes clientEmail:read, and site:read includes siteFile:read). signalIncident and project are top-level resources: conversation:read does not grant Signal Incidents and site:read does not grant projects, so a key that needs either must list signalIncident:read / project:read explicitly (or use all:read).

​
Updating scopes on an existing key

Open Settings → Integrations → Developer, choose the key, and select Edit scopes. Saving updates the key’s allowed operations without changing the secret value.