Skip to content

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.

  • 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 403 and code forbidden.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 /cameras and GET /events return 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.

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.

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

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)

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

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

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

Shown as Manage events. It is accepted at token creation, but no endpoint requires it at the moment, so granting it adds nothing.

Shown as Recording coverage. GET /cameras/{id}/coverage: which time ranges of a camera are recorded.

Shown as Raw segments. GET /cameras/{id}/segments: the recorded segment files of a camera, paginated.

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

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

Shown as Read schedules and Manage schedules. GET /cameras/{id}/schedule and PUT /cameras/{id}/schedule; the write needs an administrator owner.

Shown as Read zones and Manage zones. GET /cameras/{id}/zones and PUT /cameras/{id}/zones; the write needs an administrator owner.

Shown as Read detection. Administrator owner. GET /system/detection, GET /system/ai, GET /system/ai/plan, GET /system/ai/gpu.

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

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

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

Shown as Arm/disarm alarm. GET /alarm and PUT /alarm: read and change the armed state. It does not need an administrator owner.

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

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

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

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

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.

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.

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.