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.
The settings schema
Section titled “The settings schema”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.
Groups
Section titled “Groups”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.
Defaults
Section titled “Defaults”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.
Saving settings
Section titled “Saving settings”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.
Reading settings
Section titled “Reading settings”| 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. |
// backendconst 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.
Secrets
Section titled “Secrets”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}/settingsreports 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.
Using a secret from a panel
Section titled “Using a secret from a panel”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.
keymust be asecretsetting 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.
Private storage
Section titled “Private storage”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.
Who can use it
Section titled “Who can use it”| 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.
Limits
Section titled “Limits”| 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.
Lifetime
Section titled “Lifetime”| 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 |