Skip to content

Settings

"Who can do what, which environments, and how runs are priced." Settings is the Dashboard-own admin surface (0.4.0) — four cards, all stored in the local state store, no platform call. Writing Connections / Access / Pricing needs the settings.write capability (admin in the built-in default map); Preferences is self-scoped and ungated.

The Settings page with its four stacked cards — Connections (environment → kneo-client profile), Access (a viewer / operator / admin capability matrix plus per-role environment grants), Pricing (a blended per-1,000-token rate), and Preferences (theme).

The four cards:

Card What Covered in
Connections environment → kneo_client profile (the env-switcher source) Connecting
Access role → capabilities + per-role environment grants this page
Pricing the blended price book (approximate cost) Cost & spend
Preferences your personal UI preferences this page

Access — capabilities & environment grants

Authorization is by capability, not by fixed role. The Access card edits a role → capability map and a role → environments grant map that the BFF enforces server-side on every privileged action. The role is only the lookup key into these maps — which is why "admin" below is the built-in default, not a hardcoded rule.

The built-in default capability map

Until you save an override, these are the defaults (reassignable per role via this card):

Capability What it gates viewer operator admin
(none) — reads runs · trace · checkpoints · health · Overview · filters ✓ ✓ ✓
run.control Stop (cancel) · Resume (continue / HITL resume) – ✓ ✓
annotate write run annotations / tags – ✓ ✓
filter.write create / delete saved filters – ✓ ✓
credentials.read view the credential inventory – ✓ ✓
launch Launch (Load → Deploy → Run) – – ✓
policy.write edit an environment policy (PUT / preview) – – ✓
audit.read view the platform Audit page – – ✓
settings.write edit Connections / Access / Pricing – – ✓

Saving an Access map (PUT /api/settings/access) validates it: unknown roles or capabilities are rejected (400), and the no-lockout guard refuses any map where admin would lose settings.write (otherwise no one could ever edit Access again).

settings.write is a meta-capability — grant it sparingly

An operator with settings.write can edit the Access map itself, so they can grant any capability to any role — including their own. Treat it as Access-map administration, not an ordinary setting. Changes get a best-effort audit append; alert on kneo_dash_audit_write_failures_total.

Saving Access re-authenticates every session — including your own

The Access map carries a version; saving bumps it, and the BFF forces every session (yours included) to re-resolve its role/capabilities on the next request (ADR-009 §5). A demotion therefore takes effect immediately, without waiting for cookie expiry — and if you save a map that drops your own effective capability, you'll feel it on your next click. This is also the recovery seam: an admin who locks themselves out is recoverable by the config-pinned bootstrap admin, or the recover --reconcile --access-map flow (see the access.json reconcile runbook).

Environment grants

The second Access map (PUT /api/settings/access/environments) confines which environments a role may use. Unconfigured = unrestricted (every role may use every env). A role's grant may include "*" (all envs). Admin is never env-locked — it retains access to every environment regardless of this map (a second no-lockout guard). Unknown roles are rejected (400); env names are free-form and validated against Connections at use.

Preferences

Settings › Preferences is your personal UI preferences — self-scoped and ungated (no capability, and successful writes are not audited). It's an opaque JSON blob the SPA owns and the BFF round-trips verbatim (theme, default env, density, …), versioned for optimistic-concurrency edits. Preferences are per-operator; they never affect another operator.