Technical docs
Variables & Secrets
Public reference generated from tech docs/variables.md.
Overview
Support reference for org variables at `/variables`.
Access and scope
- `/variables` is organization-scoped. - It uses org routes under `/api/organizations/{orgId}/variables*`. - System defaults are not managed here.
Current page behavior
- Page title: `Variables & Secrets`. - Primary action: `Add`. - Empty state: `No variables or secrets`. - Table supports type filtering, date presets for `Created` and `Updated`, export, and bulk delete with undo. - Row actions are `Edit` and `Delete`. - Current columns: `Key`, `Value`, `Type`, `Added`, `Updated`. - Secret values stay masked in the table. - Export masks secret values as `••••••••`.
What users can edit
- Create sets key, value, and type (`public` or `secret`). - Current edit flow only persists the value. - The key and type are read-only in the edit dialog and are not changed by the current update request. - Current create-dialog input constraints are frontend-only: - key allows letters, digits, and `_` - if the first character is a digit, the UI prepends `_` - the current dialog does not auto-uppercase the key
Secret handling
- Secret values are obfuscated in API responses by `OrganizationVariable.safeData()`, and the table/export UI never shows the raw stored secret. - Editing a secret does not reveal the original value; users need to enter the new secret value they want saved.
Current API routes
- `GET /api/organizations/{orgId}/variables` - `POST /api/organizations/{orgId}/variables` - `PUT /api/organizations/{orgId}/variables/{variable_id}` - `DELETE /api/organizations/{orgId}/variables/{variable_id}` - `POST /api/organizations/{orgId}/variables/bulk-delete` - `POST /api/organizations/{orgId}/variables/bulk-restore` - `GET /api/organizations/{orgId}/variables/deleted`
Current support behavior
- The page deletes through soft-delete endpoints and restore is exposed through the immediate undo flow. - There is no deleted-items view on `/variables`. - The current frontend fetches `/variables` without page parameters, so it only loads the backend first page. - In current backend validation, the effective default page size is `10`. - Create rejects duplicate placeholders and reserved placeholders such as `role`, `goal`, and `instructions`. - Duplicate protection only applies to non-deleted rows because the database unique index excludes soft-deleted variables. - The current frontend uses `bulk-delete` even for single-row deletes; the single-item `DELETE /variables/{id}` route exists but is not used by this page. - `PUT /variables/{id}` currently accepts only `value`; backend comments/config still mention name updates, but the actual action ignores key/type changes.
Realtime updates
- The page listens to `variable.created`, `variable.updated`, `variable.deleted`, and `organization.updated`. - `bulk-restore` re-emits restored rows as `variable.created`, which is why undo repopulates through the same event path.
System defaults
- System defaults live on `/defaults`, not `/variables`. - That page uses `/api/admin/settings*`. - The current frontend gates `/defaults` to developer users.