Token scopes
A scope names one kind of access an API token may use. A token holds only the scopes you grant, and every scope works within the token owner’s role and camera access: a scope marked “administrator owner” below opens its endpoints only when the token belongs to an administrator. This page lists every scope from internal/api/scopes.go with the endpoints that require it, taken from the route table in internal/api/server.go.
Sessions (the web app) and the local CLI token do not use scopes: they carry their user’s full authority.
How scopes are checked
Section titled “How scopes are checked”- Token creation rejects an unknown scope and a token with no scopes.
- On each request, the endpoint’s declared scopes are compared with the token’s. A missing scope fails with
403and codeforbidden.scope. - Endpoints whose path contains a camera
{id}also check that the camera is within the token’s reach (the owner’s cameras, narrowed by the token’s camera restriction). Otherwise:403 forbidden.camera. - Lists such as
GET /camerasandGET /eventsreturn only what the token may see rather than failing. - A token can never be widened. To change its scopes, create a new token and revoke the old one.
In the tables, paths are relative to /api/v1.
Live and media
Section titled “Live and media”media:live
Section titled “media:live”Shown as Live streams (WebRTC/HLS). Opens live video.
| Endpoint | Notes |
|---|---|
GET /cameras/{id}/stream-token |
A 5-minute token for the live WebSocket |
GET /cameras/{id}/ws |
Accepts a media:live token directly as ?token= |
The preset Live view only is exactly this scope.
media:read
Section titled “media:read”Shown as Recorded playback. Reads recorded and current pictures and your exports.
| Endpoint | Notes |
|---|---|
GET /cameras/{id}/snapshot.jpg |
Current picture |
GET /cameras/{id}/frame |
A frame of recorded footage at ?t= |
GET /cameras/{id}/hls |
HLS playlist of recordings for ?from=/?to= |
GET /cameras/{id}/seg/{seg} |
One recorded segment |
POST /cameras/{id}/lease, DELETE /cameras/{id}/lease/{leaseId} |
Protect a time range from retention for up to 2 hours while you read it |
GET /export, GET /export/{id}, GET /export/{id}/download |
Your exports |
GET /shares |
Your share links; an administrator can add ?user=<id> or ?all=true |
media:write
Section titled “media:write”Shown as Exports & shares. Creates footage that leaves Aperture.
| Endpoint | Notes |
|---|---|
POST /export, DELETE /export/{id} |
Start or delete an export (Idempotency-Key supported) |
POST /shares, DELETE /shares/{id} |
Create or revoke a public share link for one of your exports |
DELETE /cameras/{id}/recordings |
Remove footage; administrator owner (checked by the handler) |
Cameras and events
Section titled “Cameras and events”cameras:read
Section titled “cameras:read”Shown as Read cameras.
| Endpoint | Notes |
|---|---|
GET /cameras, GET /cameras/{id} |
Camera settings; stream links come with the login masked, or empty |
GET /camera-groups |
Camera groups |
GET /cameras/{id}/onvif, GET /cameras/{id}/vendor |
Administrator owner |
cameras:write
Section titled “cameras:write”Shown as Manage cameras. Every endpoint needs an administrator owner.
| Endpoint | Notes |
|---|---|
POST /cameras, PUT /cameras/{id}, DELETE /cameras/{id} |
Add, change, delete a camera |
POST /cameras/test |
Test a stream address |
POST /cameras/reorder |
Order on the dashboard |
POST /camera-groups, PUT /camera-groups/{id}, DELETE /camera-groups/{id}, PUT /cameras/{id}/groups |
Camera groups |
PUT /cameras/{id}/onvif, PUT /cameras/{id}/onvif/imaging, PUT /cameras/{id}/vendor |
ONVIF picture settings and vendor extras |
events:read
Section titled “events:read”Shown as Read events.
| Endpoint | Notes |
|---|---|
GET /events, GET /events/{id} |
Events across cameras, paginated |
GET /events/{id}/detections, GET /events/{id}/thumb.jpg |
Recognised objects and thumbnail of one event |
GET /cameras/{id}/events, GET /cameras/{id}/tracks |
Events of one camera; object positions over time |
GET /feed |
The change feed (Server-Sent Events) |
GET /notify/stream |
The notification stream the web app listens to |
events:write
Section titled “events:write”Shown as Manage events. It is accepted at token creation, but no endpoint requires it at the moment, so granting it adds nothing.
Coverage and segments
Section titled “Coverage and segments”coverage:read
Section titled “coverage:read”Shown as Recording coverage. GET /cameras/{id}/coverage: which time ranges of a camera are recorded.
segments:read
Section titled “segments:read”Shown as Raw segments. GET /cameras/{id}/segments: the recorded segment files of a camera, paginated.
Storage and schedules
Section titled “Storage and schedules”storage:read
Section titled “storage:read”Shown as Read storage.
| Endpoint | Notes |
|---|---|
GET /system/storage |
Storage usage summary |
GET /cameras/{id}/destinations |
Where a camera records and mirrors |
GET /system/storage/disk, GET /system/storage/locations |
Administrator owner |
POST /system/storage/locations/allocate/preview |
What a smaller allocation would delete; read-only; administrator owner |
storage:write
Section titled “storage:write”Shown as Manage storage. Every endpoint needs an administrator owner, and several can delete footage by shrinking an allocation.
| Endpoint | Notes |
|---|---|
PUT /system/storage |
Storage settings |
POST /system/storage/reserve |
Hard space reservation |
POST /system/storage/locations, PUT /system/storage/locations/{id}, DELETE /system/storage/locations/{id} |
Destinations |
POST /system/storage/locations/test, …/allocate, …/assign, …/reorder |
Test, allocate, assign cameras, order |
PUT /cameras/{id}/destinations |
A camera’s destinations and mirrors |
schedules:read and schedules:write
Section titled “schedules:read and schedules:write”Shown as Read schedules and Manage schedules. GET /cameras/{id}/schedule and PUT /cameras/{id}/schedule; the write needs an administrator owner.
Zones and detection
Section titled “Zones and detection”zones:read and zones:write
Section titled “zones:read and zones:write”Shown as Read zones and Manage zones. GET /cameras/{id}/zones and PUT /cameras/{id}/zones; the write needs an administrator owner.
detection:read
Section titled “detection:read”Shown as Read detection. Administrator owner. GET /system/detection, GET /system/ai, GET /system/ai/plan, GET /system/ai/gpu.
detection:write
Section titled “detection:write”Shown as Manage detection. Administrator owner.
| Endpoint | Notes |
|---|---|
PUT /system/detection, POST /system/detection/test |
Detection settings and a test run |
POST /system/ai/enable, …/cancel, …/disable |
Turn local object recognition on or off (starts downloads) |
POST /system/ai/models, DELETE /system/ai/models/{id} |
Add or remove your own model |
DELETE /system/ai/files |
Remove downloaded runtime and model files |
Automation and alarm
Section titled “Automation and alarm”automation:read
Section titled “automation:read”Shown as Read automations.
| Endpoint | Notes |
|---|---|
GET /notify/channels, GET /notify/rules |
The owner’s notification channels and rules |
GET /push/key |
The web push public key |
GET /automations |
Administrator owner |
GET /webhooks, GET /webhooks/{id}/deliveries |
Administrator owner; includes webhook signing secrets |
automation:write
Section titled “automation:write”Shown as Manage automations.
| Endpoint | Notes |
|---|---|
POST /notify/channels, PUT …/{id}, DELETE …/{id}, POST …/{id}/test |
The owner’s notification channels |
POST /notify/rules, PUT …/{id}, DELETE …/{id}, POST …/{id}/test |
The owner’s notification rules |
POST /push/subscribe, POST /push/unsubscribe |
Web push subscriptions |
POST /automations, PUT /automations/{id}, DELETE /automations/{id}, POST /automations/{id}/test |
Administrator owner |
POST /webhooks, PUT /webhooks/{id}, DELETE /webhooks/{id}, POST /webhooks/{id}/test |
Administrator owner |
alarm:arm
Section titled “alarm:arm”Shown as Arm/disarm alarm. GET /alarm and PUT /alarm: read and change the armed state. It does not need an administrator owner.
Site and system
Section titled “Site and system”site:read
Section titled “site:read”Shown as Read site settings.
| Endpoint | Notes |
|---|---|
GET /system/settings, GET /system/site, GET /system/hardware |
Display settings, site location, hardware profile |
GET /system/weather/now, …/at, …/range, GET /system/astro |
Weather and sun and moon times |
GET /system/weather, GET /system/geocode, GET /system/geo/resolve |
Administrator owner; the geocode search contacts Open-Meteo |
GET /system/ha, GET /system/ha/sensors, GET /system/interop, GET /system/oidc, GET /system/integrations/eufy |
Integration settings; administrator owner; passwords and secrets are never included |
site:write
Section titled “site:write”Shown as Manage site. Every endpoint needs an administrator owner.
| Endpoint | Notes |
|---|---|
PUT /system/settings, PUT /system/site, PUT /system/hardware, PUT /system/weather, PUT /system/playback |
Site and display settings |
PUT /system/ha, PUT /system/interop |
Home Assistant, ONVIF and HomeKit |
PUT /system/oidc |
Single sign-on settings |
system:read
Section titled “system:read”Shown as System health.
| Endpoint | Notes |
|---|---|
GET /system/bitrate |
Live bitrate |
GET /system/status, GET /system/metrics, GET /system/diagnostics |
Administrator owner |
GET /system/audit, GET /system/audit/verify |
The activity log and its chain check; administrator owner |
Without a scope
Section titled “Without a scope”Any token can call these, whatever scopes it holds:
| Endpoint | Notes |
|---|---|
GET /auth/me |
The owner’s profile |
GET /capabilities, GET /openapi.json |
What the server supports; the API description |
GET /users/me/preferences, PUT /users/me/preferences |
The owner’s display preferences |
GET /auth/passkeys |
Names and dates of the owner’s passkeys (no key material) |
GET /ext/panels, GET /ext/nav |
Which extension panels and rail entries to show |
Only the extension’s own token
Section titled “Only the extension’s own token”GET /ext/{id}/settings, POST /ext/{id}/fetch and the storage routes under /ext/{id}/kv act as extension {id}. Of all tokens, only that extension’s own backend token may call them, with no scope needed. Any other token, including a personal token with every scope and another extension’s token, is refused with 403 and the code forbidden.extension, and so is the CLI token. A signed-in session may call them under the panel rules in Routes that act as the extension.
Never available to tokens
Section titled “Never available to tokens”These endpoints are session-only. A token is refused with 403 (“not available to API tokens”), whatever its scopes and owner, because they could take over an account, leak secrets, destroy data or stop the system:
| Area | Endpoints |
|---|---|
| Users | GET /users, POST /users, PUT /users/{id}, DELETE /users/{id} |
| Tokens | GET /tokens, POST /tokens, DELETE /tokens/{id} |
| Your own account | POST /auth/password, POST /auth/2fa/setup, …/enable, …/disable, POST /auth/passkey/register/begin, …/finish, DELETE /auth/passkeys/{id} |
| Your devices | GET /auth/sessions, DELETE /auth/sessions/{id}, POST /auth/sessions/revoke-others |
| Backup and maintenance | GET /system/backup, POST /system/restore, POST /system/restart, POST /system/purge, POST /system/reindex |
| Extensions | Installing, enabling, updating, removing, re-scoping, files, logs, settings writes and the panel broker under /ext/… |
| Integration secrets | The Eufy account (PUT /system/integrations/eufy and its sign-in challenges) and the live-view key (/integrations/live-key) |
The local CLI token is not a token in this sense: it is a full administrator credential and can reach these endpoints. The routes that act as one extension are the exception: the CLI token is refused there.
Choosing scopes
Section titled “Choosing scopes”| Use | Scopes |
|---|---|
| A wall display or a player showing live video | media:live, restricted to the cameras shown |
| A script that saves a picture every few minutes | media:read, restricted to one camera |
| A dashboard of events and recording state | cameras:read, events:read, coverage:read |
| Arming from a home automation system | alarm:arm |
| A monitoring check | system:read (with an administrator owner for /system/status) |
The preset Everything grants all scopes: on an administrator’s token that is close to full control of the system, short of the session-only operations above.
Related: The API and tokens, Endpoint reference, Security model and hardening.