Skip to content

Permissions

An extension’s permissions block is the complete list of what it may do. This page explains each permission, the API scopes and camera grants it turns into, how network access is bounded, and how a UI panel’s rights combine with those of the person looking at it.

Extension permissions are not a separate system. They become the same API scopes and per-camera grants that any API token carries:

  • A backend gets its own scoped API token. Every call it makes is checked like a call from any other token.
  • A UI panel never holds a token. Its calls go through Aperture’s broker, which checks them against the extension’s scopes and the viewing user’s own rights together.

Two permissions have no API scope: network (which hosts the extension may reach) and storage (its private key-value store). Everything is denied by default: an absent or empty permissions block grants nothing.

The mapping lives in dataDomainScopes in internal/ext/manifest.go. A test (TestExtScopesAreKnown) fails the build if the mapping ever names a scope the API does not enforce.

Manifest entry Becomes Consent wording
data.<domain>: "read" the <domain>:read scope “Read your …”
data.<domain>: "write" <domain>:read and <domain>:write “Read and change your …”
data.media: "live" media:live only “Read your media”, plus the camera line “Watch your cameras’ live video”
alarm: "arm" alarm:arm “Read and change your alarm”
system: "read" system:read “Read your system”
cameras: "all" or ["id", …] the camera grant on the token A camera section with its own line and picker
network: [ … ] the backend’s Deno --allow-net list and the panel’s net.fetch allow-list “Connect over the internet to … — it can send your data there”, and variants below
storage: true a private key-value namespace “Keep its own settings in a private folder”
settings: [ … ] the same namespace, plus a form “Store its settings — including any secrets you enter — in a private folder”

The consent screen joins all API scopes into one line: the domains in alphabetical order, with “Read and change” when any of them is a write (or alarm), and “Read” otherwise. An extension that reads cameras and events and changes the site shows “Read and change your cameras, events, site”. Every consent list ends with “It cannot read your recordings files, your database, or your passwords.”

Domain read write live
cameras cameras:read cameras:read, cameras:write
events events:read events:read, events:write
coverage coverage:read
segments segments:read
media media:read media:read, media:write media:live
storage storage:read storage:read, storage:write
schedules schedules:read schedules:read, schedules:write
zones zones:read zones:read, zones:write
detection detection:read detection:read, detection:write
site site:read site:read, site:write
automation automation:read automation:read, automation:write

A domain or level that is not in this table fails the install. Scopes lists which API routes each scope opens.

Each domain takes one level, so media is either "read", "write" or "live". An extension that asks for "live" cannot also read recorded media.

data.storage is the scope for Aperture’s own storage locations (where recordings go). It has nothing to do with the top-level storage: true, which is the extension’s private key-value store. You may want either, both or neither.

Some routes require an administrator on top of the scope; for example changing a camera needs cameras:write and an administrator. For a backend, the administrator is the token’s owner: the administrator who installed the extension, or, for an install made with the CLI token, the first administrator account. For a panel, it is the person viewing it, so the same panel can change a camera for an administrator and get “administrator access required” for a viewer.

Camera access is the main privacy control, so it is opt-in and explicit. permissions.cameras takes one of:

Value Meaning
absent No camera access. The extension cannot read camera data.
"all" Every camera, including cameras added later.
["front_door", "garage"] At most these cameras. The list is a ceiling, written as camera ids.

An extension that asks for cameras, events, coverage, segments or media under data must also ask for cameras, or the install fails: “this extension reads camera data but does not request cameras”. A panel that only places a control and reads no camera data does not need to ask, and gets no camera section at consent.

A list of ids only means something on a server where those ids exist. Ids that do not exist do not appear in the picker. For an extension you share, "all" is the portable choice; the administrator narrows it at install.

The manifest’s request is a default. At install the administrator chooses:

  • for an "all" request: All cameras (including cameras added later) or Only the cameras I choose (exactly these; a camera added later is not granted);
  • for a list request: any subset of the listed cameras that exist.

Afterwards the choice lives in the Cameras section of the extension’s row in Settings › Extensions. Saving it stores the new grant, revokes the backend’s token and restarts the backend with a new token limited to the new grant. Nothing starts while the extension is disabled or the extension gate is off. Changing cameras is the administrator’s decision, not a new permission, so it never asks for consent.

An update keeps your choice, fitted to the new version’s request:

  • If the new version asks for every camera, or for none, the grant stays as it is.
  • If it names specific cameras and your grant was every camera, the grant becomes that list.
  • If you had picked cameras, the grant keeps those the new list still names. If the new list names none of them, the grant becomes the new list, and the update asks for consent first.

The server refuses an empty selection (“select at least one camera to grant”) and any camera outside a list request (“camera … was not requested by this extension”). The same check runs when the choice is changed through PUT /api/v1/ext/{id}/cameras.

One decision controls both what the extension can read and where its panels appear:

  • Data: API calls for a camera outside the grant fail with 403, and lists such as GET /cameras and the change feed leave those cameras out.
  • Placement: panels in the camera slots (camera-detail, player-toolbar, player-osd) appear only on granted cameras. An extension granted all cameras, or one that asked for none, shows its camera panels on every camera.
  • Settings: a camera field in the extension’s settings only offers, and only accepts, granted cameras.

A grant never widens anyone’s access:

  • A backend sees the cameras in its grant that its token’s owner may see. An all-cameras grant means everything the owner may see. Since the owner is an administrator, that is normally every camera.
  • A panel sees the cameras in the grant that the viewing user may see. A viewer allowed one camera sees one camera in a panel granted all of them.

permissions.network lists the hosts an extension may reach. It is the only way an extension reaches anything outside Aperture.

Entry Allowed host Consent line
"https://hooks.example.com" hooks.example.com “Connect over the internet to hooks.example.com — it can send your data there”
"http://192.168.1.50:2020" 192.168.1.50:2020 “Connect over the internet to 192.168.1.50:2020 — it can send your data there”
"http://127.0.0.1:8788" 127.0.0.1:8788 “Talk to 127.0.0.1:8788 — a service running on this machine, not over the internet”
"{{setting:ha_url}}" the host and port of the ha_url setting’s current value “Connect to a server you configure in its settings — it can send your data there”
"{{setting:cameras.address}}" the host and port in the address column of every row of the cameras group setting the same line

Only localhost, ::1 and 127.x.x.x count as this machine. Everything else, including addresses on your own network, is worded as the internet.

A setting reference lets the user, not the author, choose the host. The allow-list follows the value the administrator saved, and changing the value needs no new consent. An update that adds a host, or refers to a setting the old version did not, does ask again (see Updates and consent). A group reference serves extensions that talk to several devices the user names: each row adds exactly the address typed into it, port included.

A backend’s hosts become Deno’s --allow-net flag, built when the backend starts. Setting references are resolved at that moment, and saving settings restarts the backend, so the flag always matches the saved values. Aperture also adds its own API host (the host in APERTURE_API) so the SDK works; with no network permission, that is the only host a backend can reach.

Deno decides what each entry allows. An entry with a port allows that port only. An entry without a port (from a URL such as https://hooks.example.com) allows that host on every port. The same flag also governs listening, so a backend can only serve on an address it declared, which is why the Tapo and Eufy examples list their own 127.0.0.1 control ports.

A request to any other host fails inside the backend with Deno’s NotCapable error.

A panel cannot open network connections itself. window.aperture.net.fetch asks Aperture’s server to make the request (POST /api/v1/ext/{id}/fetch), and the server checks it first:

  • The URL’s host and port must equal one allowed entry exactly. https://hooks.example.com:8443/x does not match an entry for hooks.example.com.
  • Setting references are resolved on every request.
  • Methods are GET, POST, PUT, PATCH and DELETE. A Host header from the panel is ignored.
  • Redirects are not followed; the panel gets the 3xx response, so a redirect cannot lead to an undeclared host.
  • The request times out after 12 seconds, and at most 256 KiB of the response body is returned.
  • All extensions together may make 10 such requests per second, with bursts of 20.
  • {{secret:key}} in a header value or the body is replaced on the server with the extension’s own secret setting. See Settings and storage.

When a setting a network entry refers to is empty or not a valid URL, a request to an unlisted host fails with “the server address is not set (or is not a valid URL) — configure it in this extension’s settings”. Otherwise an unlisted host fails with “host … is not one this extension may reach”. For a group, one blank or malformed row is enough to report the extension as not configured.

Only two kinds of caller may use this route: a signed-in user’s session, which is how the web app relays a panel, and the extension’s own backend token. For a session, the extension must be enabled (with the gate on), and an extension granted specific cameras serves only a user who may see at least one of them. Any other API token, including another extension’s, and the CLI token get 403 with the code forbidden.extension. See Routes that act as the extension.

storage: true gives the extension a private key-value store, separate from other extensions and from Aperture’s settings. Declaring settings implies it, because settings are kept in the same store; you never need both. Its backend reads and writes it with its token. In a panel, only administrators can use it. Limits and access rules are on Settings and storage.

A UI panel runs in the browser of whoever is looking at it, so it acts with that person’s rights, cut down to the extension’s. Every window.aperture.request, cameras and events call goes to POST /api/v1/ext/{id}/broker. The broker builds a one-off identity from:

Part Taken from
User and role The signed-in viewer
Camera access The viewer’s cameras intersected with the extension’s grant
Scopes The extension’s scopes
Credential class API token, so token rules apply

It then sends the request through Aperture’s normal router, with its normal checks. The consequences:

  • A panel can never do more for someone than that person could do unaided, and never more than its manifest declared.
  • The same panel may show a viewer less than an administrator. That is correct behaviour.
  • Administrator-only routes need the viewer to be an administrator.
  • Routes that tokens may never use (see below) are refused here too.
  • The extension’s token never reaches the browser; a UI-only extension has no token at all.

The broker accepts GET, POST, PUT, PATCH and DELETE, and a path relative to /api/v1 that starts with /, does not start with /api and contains no ... It is available only to signed-in sessions, only while the gate is on and only for an enabled extension.

From a panel Administrator viewing Viewer viewing
API calls through the broker Extension scopes, all granted cameras Extension scopes, granted cameras the viewer may see; administrator-only routes refused
settings.get, settings.all Non-secret values Non-secret values; camera values, and list rows tied to a camera, only for granted cameras the viewer may see
storage.* Allowed Refused: “extension storage is available to administrators only”
net.fetch Allowed Allowed; for an extension granted specific cameras, only if the viewer may see one of them

Raw storage is limited to administrators because it has no per-key access control: anything a viewer could read through a panel, they could read from the browser’s developer console as well. Data meant for viewers should come from the extension’s backend through the API, where it is scoped.

Three routes act as the extension itself: they spend its secrets, reach its declared hosts or read its private data. They are POST /api/v1/ext/{id}/fetch, GET /api/v1/ext/{id}/settings and the storage routes under /api/v1/ext/{id}/kv. Each accepts only:

  • the extension’s own backend token, with its full view of its settings and storage, secrets included;
  • a signed-in user’s session: the web app relaying one of the extension’s panels, or the extension manager. For fetch and settings, a session needs the extension enabled and, for an extension granted specific cameras, a user who may see at least one of them; an administrator’s session reads any extension’s settings form, enabled or not. Storage needs an administrator.

Every other credential is refused with 403 and the code forbidden.extension: a personal API token, another extension’s backend token, and the CLI token. Saving settings (PUT /api/v1/ext/{id}/settings) is a separate route, open only to an administrator’s session. The OpenAPI document marks these routes with x-extension-self.

An update is applied without a new consent dialog only when it asks for nothing the installed version did not have. Aperture compares the update’s manifest with the installed one (ext.NewPermissions in internal/ext/perms.go) and asks again for any of these:

  • a new API scope;
  • a new network host, or a host taken from a setting the old version did not refer to;
  • cameras where it asked for none before, every camera where it named specific ones, or a camera id the old list did not name;
  • private storage it did not have;
  • a backend, where the installed version was UI only;
  • a camera grant that the new request would change to cameras you did not pick (see Choosing and changing the grant).

The web app checks both the update’s published manifest and the bundle it actually downloaded, and opens the consent dialog if either asks for more. The server enforces the same rule: applying such an update without consent fails with 409 and the code consent_required.

Some operations have no scope at all and are open only to a signed-in session or the CLI token. No manifest can reach them, whatever it asks for:

  • users and API tokens: listing, creating, changing, deleting;
  • your own password, two-factor authentication, passkeys and signed-in devices;
  • backup, restore, restart, reindex and purge;
  • installing, configuring and managing extensions, and the extension gate;
  • the Eufy account integration, which holds a cloud password.

The manifest · UI panels · Settings and storage · Extension security · Scopes