key
list and mint api keys from the terminal. superadmin keys only — the backing route requires user=*:admin. new keys inherit the calling key's scopes and cannot widen them.
⚠️
key createprints the rawowk_*value exactly once. the server never returns it again. copy it into a secret manager or env file immediately — there is no recovery path if you lose it.
most key management belongs in the dashboard
this command drives /api/account/api-keys, the only key route that accepts
api-key authentication. that route is deliberately narrow:
- superadmin only — it is wrapped in a platform-capability check, so the
calling key needs
user=*:admin. anything less returns403 scope_insufficient. - scopes are inherited, not chosen —
createclones the calling key's scopes verbatim. a key can never widen its own privileges, so you cannot mint aninstaller- oruser-scoped key unless the calling key already holds it. - no scope editing, rotate, or revoke — those live on
/api/keys/{keyId}, which takes a session or firebase id token and rejects api-key auth outright.
for custom scopes, editing an existing key's scopes, rotation, revocation, or anything a non-superadmin needs, use settings → api keys in the dashboard.
list
synopsis — owlette key list [--json]
lists your api keys. never returns raw key values — only the display prefix.
owlette key list| column | meaning |
|---|---|
id | key id, used by the dashboard's edit/rotate/revoke actions |
name | human-readable label |
prefix | first 15 characters of the raw key, for audit correlation |
created / last used / expires | dates, — when unset |
scopes | <resource>=<id>:<perm>[,<perm>...] per scope, or legacy (full access) |
--json emits the raw response envelope for scripting.
create
synopsis — owlette key create [--name <name>] [--json]
mints a key carrying the same scopes as the key you are calling with. there
is no --scope or --preset flag — the backing route does not accept one.
owlette key create --name "ci publisher"the raw key is the final line in table mode, so this is a usable idiom:
OWLETTE_TOKEN=$(owlette key create --name ci | tail -1)exit codes
| code | meaning |
|---|---|
0 | success |
1 | api error — the message carries the status and problem code |
2 | no token configured; run owlette auth login or set OWLETTE_TOKEN |
notes
owlette auth loginalready stores a key for you via the device-code flow; you do not needkey createto get started.- keys expire (default 90 days, max 365). there is no non-expiring option, and
nothing currently emails you before one lapses — check
key listor the dashboard periodically.
installer
superadmin only. Installer commands require a superadmin user session or an API key with installer=*:read for list/latest, installer=*:write for upload, and installer=*:admin for set-latest/delete.
listen
listen opens the site's scoped SSE stream and forwards each non-liveness event to a local HTTP endpoint. it is a long-running developer helper for testing webhook-style consumers against the owlette api. tier: [ready], with the current server stream limited to liveness events until production event fanout ships.