Skip to content

Settings and storage

An extension can declare its own settings, such as a server address, an access token or a mode. Aperture turns the declaration into a form on the extension’s row, validates what the administrator enters, and keeps the values in the extension’s private store, where both the backend and the panels can read them. This page covers the settings schema, secrets, and the private store behind both.

The server side lives in internal/api/ext_settings_handlers.go and internal/api/ext_kv_handlers.go.

settings is a top-level array in manifest.json. Declaring it gives the extension private storage, so you do not also write "storage": true.

"settings": [
{
"key": "mode",
"label": "Mode",
"type": "select",
"required": true,
"default": "eco",
"help": "Eco checks the device once a minute.",
"options": [
{ "value": "eco", "label": "Eco" },
{ "value": "fast", "label": "Fast" }
]
}
]
Field Type Required Meaning
key string yes The name the extension reads the value by. Matches [a-z0-9][a-z0-9._-]* and is unique.
label string yes The label on the form, also used in error messages.
type string yes One of the types below.
help string no Text shown under the field.
placeholder string no Hint inside an empty text, secret, number or address box.
required boolean no Saving fails while the field is empty. Required fields show a red asterisk.
default any JSON value no Written at install for scalar fields other than secret.
options array of { value, label } for select The choices. Each value must be non-empty; label falls back to the value.
fields array of fields for group The columns of each row.
Type Form control Stored as Checked on save
text Text box The text Must be a string
secret Password box with a key icon The text, write-only Must be a string
number Number box The number as text, such as "500" Must be a number, or a string that parses as one
boolean Switch "true" or "false" Must be true or false
select Drop-down; an optional field also offers “—” The chosen value Must be one of the options
url Text box The address, trimmed Must be an absolute http or https URL with a host
camera Drop-down of the extension’s granted cameras, starting with “Select a camera…” A camera id Must be a camera the extension may use
group A table of rows with Add and a remove button per row; “None yet.” when empty A JSON array of row objects, each value a string Each row is checked field by field

A url setting can also decide where the extension may connect, with {{setting:key}} in permissions.network; see Permissions. A camera value that is no longer granted shows as “front_door (not granted)” until you pick another.

A group is a repeatable list, for configuration such as “this camera controls that light”. Its fields may use any type except group and secret, so groups do not nest and rows hold no secrets.

{
"key": "lights",
"label": "Camera → light",
"type": "group",
"required": true,
"help": "Map each camera to the light to control while you view it.",
"fields": [
{ "key": "camera", "label": "Camera", "type": "camera", "required": true },
{ "key": "entity", "label": "Light entity", "type": "text", "required": true, "placeholder": "light.hallway" }
]
}

A required group needs at least one row. A required column must be filled in on every row.

At install, Aperture writes the default of every text, number, boolean, select, url and camera field into the store, so the backend and panels see it before anyone opens the form. Secrets must be entered, and groups start empty. An update writes the defaults of fields that are new in that version and never overwrites a stored value.

Only an administrator, signed in to the web app, can save settings. The form on the extension’s row sends every value at once to PUT /api/v1/ext/{id}/settings as { "values": { … } }. Aperture checks every field before it writes any, so a bad field never leaves half the settings saved. The first problem comes back as the error, for example:

Message Cause
Home Assistant URL must be an http(s) URL, e.g. https://192.168.1.10:8123 A url field holds something else
Mode: “turbo” is not one of the allowed options A select value outside its options
Camera: camera “garage” is not one this extension may use A camera outside the grant
Long-lived access token is required A required field is empty, or a required secret has never been set
Camera → light needs at least one entry A required group is empty
Camera → light entry 2: Light entity is required A required column is empty in a row
unknown setting “colour” The request names a key the schema does not declare

After saving, Aperture restarts the extension’s backend, if it has one and is enabled, so it reads the new values and its network permission follows any changed address. The form says so: “Saving restarts the extension so it picks them up.” A UI-only extension has nothing to restart; its panels read the new values on their next call. Saving settings is not a permission change and never asks for consent.

When an update removes a setting, or changes its type, its stored value is deleted, because the old value may not fit the new type. Settings that keep their key and type keep their values.

Where How What you get
Panel await window.aperture.settings.get("mode") A string for a scalar, or null when unset. An array of row objects for a group, empty when unset. Secrets always read as null.
Panel await window.aperture.settings.all() An object of all non-secret values. Unset scalars and all secrets are absent; groups are arrays.
Backend await aperture.storage.get("mode") The stored string, secrets included. A group is a JSON string.
// backend
const mode = (await aperture.storage.get("mode")) ?? "eco";
const lights = JSON.parse((await aperture.storage.get("lights")) ?? "[]") as { camera: string; entity: string }[];
const enabled = (await aperture.storage.get("notify")) === "true";
const interval = Number(await aperture.storage.get("interval_s")) || 60;

Every signed-in user, viewers included, can read an extension’s non-secret settings while it is enabled, because its panels need them. For a viewer, a camera value, and a group row tied to a camera, is left out unless the camera is both granted to the extension and one the viewer may see; an extension granted specific cameras answers only users who may see one of them. An administrator’s session reads any extension’s settings, enabled or not, and the extension’s own backend reads them through storage. No other API token, and not the CLI token, can read them: they get 403 with the code forbidden.extension. Do not put anything confidential in a non-secret field.

A secret setting is write-only:

  • No client ever gets the value back: not a panel, not the settings API, not an administrator. GET /api/v1/ext/{id}/settings reports only whether each secret is set ("secretSet": { "ha_token": true }).
  • The form shows “•••••••• — set (leave blank to keep)” once a value is stored. Typing a new value replaces it; leaving the box empty keeps the stored one.
  • The only reader of the plain value is the extension’s own backend, on the server, through its token.

Secrets are protected by access rules, not encryption: they are stored as plain text in Aperture’s database, which only root can read on the server. A backup of the database contains them.

A panel never sees a secret. Instead it writes a placeholder, {{secret:key}}, in a header value or the body of window.aperture.net.fetch. Aperture’s server replaces it before sending the request to the declared host:

const r = await window.aperture.net.fetch(base + "/api/states/light.hallway", {
headers: { "Authorization": "Bearer {{secret:ha_token}}" },
});

The substitution follows strict rules:

  • It happens in header values and the body only. A placeholder in the URL is sent as written.
  • key must be a secret setting declared by the same extension. Anything else fails with “{{secret:ha_tokn}} is not a declared secret setting”.
  • An unset secret fails with “secret ha_token is not configured yet”.
  • The value comes from the store of the extension the request is made for, so two extensions with a secret of the same name never see each other’s value.
  • The request can only go to the extension’s declared hosts.

A backend has no placeholder substitution. It reads the secret with storage.get and uses it directly.

Every extension with storage: true or a settings block has a private key-value store, the ext_kv table in Aperture’s database. Settings live in it under their keys, and the extension can keep its own state beside them with storage.set.

Caller Access
The extension’s backend, with its token Its own store only; every key, secrets included
Another extension’s token, a personal API token, or the CLI token Refused with 403 and the code forbidden.extension (for a token: “an API token may only act for its own extension”)
An administrator’s session, through a panel or the web app Any extension’s store; secret keys read as absent
A viewer, through a panel Refused: “extension storage is available to administrators only”
An extension that declared neither storage nor settings Refused: “this extension did not request storage”

The store is shared by everyone who uses the extension: it is not kept per user.

Limit Value
Keys per extension 1000, settings included
Total size of values per extension 1 MiB
One value 64 KiB
Key length 256 characters, no NUL
Writes and deletes 25 per second with bursts of 50, shared by all extensions

Over a quota, a write fails with HTTP 507 and “extension storage quota exceeded”. Over the write rate, it fails with HTTP 429 and “storage is being written too quickly; slow down”. Values are strings; encode anything structured with JSON.stringify.

Event The store
Disable, or turn off the extension gate Kept
Update or revert Kept, except settings the new version removed or retyped
Uninstall Deleted

The manifest · Permissions · The SDK · UI panels