Scopes
Each External App is granted a set of scopes. Every API endpoint requires one or more scopes; if the calling key lacks a required scope, the request is rejected with 403 Forbidden.
Scope strings follow the verb:resource convention. read covers GET and equivalent list/detail endpoints. write covers POST, PATCH, PUT, and DELETE.
Available Scopes
| Scope | Grants |
|---|---|
read:cameras |
List and inspect cameras, including pair status and capabilities. |
write:cameras |
Create, update, pair, unpair, and delete cameras. |
read:events |
Query activity events, detections, and event metadata. |
write:events |
Acknowledge, annotate, or manually create events. |
read:faces |
List enrolled face profiles and read enrollment metadata. |
write:faces |
Enrol new faces, update profile names, delete enrolments. |
read:areas |
List configured areas, zones-of-area, and area attendance config. |
write:areas |
Create, update, and delete areas (including pin positions). |
read:sites |
List sites accessible to the key's organisation. |
read:attendance |
Query attendance records, punches, slots, and daily summaries. |
read:zones |
List zones and zone metadata. |
write:zones |
Create, update, and delete zones. |
read:recordings |
List and download archived recordings and clips. |
write:recordings |
Trigger on-demand clip generation and manage retention overrides. |
read:sensors |
Read sensor metadata and latest readings. |
write:sensors |
Create, update, and delete sensor configurations. |
read:alerts |
List alerts and alert delivery history. |
write:alerts |
Create, acknowledge, and resolve alerts; manage alert rules. |
mcp:invoke |
Invoke MCP tools via the MCP server endpoint (see MCP Tools). |
Choosing Scopes
Grant the minimum scopes your integration needs. A read-only dashboard rarely needs more than read:cameras, read:events, and read:attendance. A facility-management bot may need write:alerts and write:areas but should never receive write:faces unless it actually enrols people.
Inspecting a Key's Scopes
The Admin UI shows the granted scopes on the External App detail page. Programmatically, GET /api/v1/auth/me returns the calling key's scopes.
Scope Mismatch Errors
{
"detail": "insufficient_scope",
"required": "write:cameras",
"granted": ["read:cameras", "read:events"]
}Status: 403 Forbidden. Fix: rotate the key with the additional scope, or use a different key.