Skip to main content

System Keys

System Keys are long-lived API keys used for service-to-service authentication against the Lumio API. Unlike OAuth clients (which act on behalf of users) or user API keys (which act on behalf of a single account), a system key authenticates an internal Lumio service such as an external bot worker, a deployment health-check script, or a backend job. They bypass per-account permission guards and should be minted sparingly.

Where to find it​

Admin sidebar → System (/system) - the System API Keys card. System Keys and System Connections share this page.

Quick start​

  1. Open Admin → System.
  2. Scroll to the System API Keys card.
  3. Click Create Key.
  4. Enter a descriptive label (e.g. Twitch Bot Key) and select at least one scope from the searchable scope picker.
  5. Click Create Key and copy the revealed key immediately - it is shown exactly once, stored hashed in the DB.
  6. Use it as a bearer token in the Authorization header for internal service calls.

Detailed walkthrough​

System API Keys card​

Shows a key count ("N key(s)") and one card per key, not a table. Each key card shows:

  • Label - human-friendly name given at creation, with the key's non-secret prefix in monospace next to it.
  • Permissions - the scoped permission list, as chips.
  • Created and Last used - dates on one line; "Last used" is omitted when the key has never been used.
  • Revoke - a red button, gated on system-keys:delete. It deletes immediately with no confirmation prompt.

Create System API Key form​

Clicking Create Key (gated on system-keys:create) opens an inline card form, not a dialog:

  • Label - free text, e.g. Twitch Bot Key.
  • Scopes - a searchable, category-grouped picker (ZAF-1214). The Create button stays disabled until a label is entered and at least one scope is selected - and while the scope registry is still loading or failed to load.

The picker is driven entirely by the backend registry - never a hardcoded list. On open it fetches GET /v1/admin/system-key-permissions (GraphQL adminSystemKeyPermissions, guarded on system-keys:read) and renders every returned scope, grouped by category with a search box across the ~130 scopes. Category headers are localised (en/de); a category with no translation falls back to a humanised form of its registry key, so a scope is never silently dropped. Each scope is shown by its canonical key (e.g. chat:write) - the identifier the mint validates - rather than a separately maintained label that could drift (ZAF-428). Because the picker consumes the same registry the mint validates against, it can never offer a scope the create path rejects. Before ZAF-1213/1214 the dialog rendered a hardcoded 13-string list that the mint validated against the operator registry alone - every one of those chips was rejected and the whole flow was non-functional.

The assignable registry is lo_auth::rbac::system_key::get_assignable_permissions() (ZAF-1213): it unions the platform-operator registry (all_admin_permissions()), the account-scope service registry (events:*, chat:*, overlays:*, connections:*, …) and the user-scope registry, then removes a two-category deny-list: credential minting (system-keys:create, apikeys:create/apikeys:edit, tokens:create, admin-roles:create/edit/delete, oauth-clients:create) and tenant/platform destruction (accounts:delete, account:delete, admin:privacy-erase). Both create paths (adminCreateSystemKey and POST /v1/admin/system-keys) validate every requested permission against this one registry.

Empty and error states are explicit, not a silently blank list. The registry read is guarded on system-keys:read, which is a different guard from the system-keys:create gate on the Create button - an operator holding only system-keys:create can open the form but get a 403 on the registry read. In that case the picker shows an error state naming the missing system-keys:read requirement and a Retry button, and Create stays disabled. A registry that resolves but is empty shows a distinct "nothing assignable" notice.

Wildcards (admin:*, *:*) are not mintable through this dialog (ZAF-1213). They stay legitimate only for config-provisioned system keys; the self-service mint path rejects them. An operator-class key that needs platform-admin reach is granted the explicit admin:access scope (or specific admin permissions), never a wildcard. There is no admin:access auto-injection on the system-key mint - a machine credential is not a dashboard seat.

audit:ingest is the narrow grant the identity app (apps/id) needs to write user-scope security events (user:login, user:oauth_granted) to POST /v1/internal/audit-ingest. It is system-key-only in effect: the ingest endpoint requires a System key, so a human admin who happens to hold audit:ingest in an admin role can never write with it. Mint a dedicated key that carries only audit:ingest and nothing else - see Provisioning the apps/id audit-ingest key.

Submit invokes POST /v1/admin/system-keys; the response contains the plaintext key only once.

API Key Created reveal dialog​

Warning-styled, one-time display:

  • Title: "API Key Created - Save Your Key".
  • Body: "This key will only be shown once. Copy it now and store it securely."
  • Buttons: Copy Key, Dismiss.

Revocation​

Revoke deletes the key row immediately - there is no confirmation dialog. Any subsequent request using that key returns 401. There is no soft-disable / re-enable flow - rotation is delete + recreate.

Common scenarios​

  • Mint a key for a new bot worker - label it after the worker (kick-bot-prod), store the secret in the secrets manager, configure the worker to send Authorization: Bearer <key>.
  • Rotate a leaked key - create a new key, update the consumer to use it, then revoke the old one.
  • Audit inactive keys - scan the "Last used" line on each card and revoke keys with no recent usage. The list is not sortable.

Provisioning the apps/id audit-ingest key​

The identity app (apps/id) writes user-scope security events (user:login, user:oauth_granted) to the Rust API via POST /v1/internal/audit-ingest, authenticated by a System key with the narrow audit:ingest grant. Without that key those events are silently dropped and apps/id's GET /api/health reports audit_ingest_configured=false. To provision it:

  1. Open System → System Keys and click Create Key.
  2. Label it for the environment, e.g. apps-id-audit-ingest-prod.
  3. In the scope picker, search for audit:ingest and select only that scope - nothing else. A dedicated single-grant key keeps the blast radius of a leak to audit ingest alone.
  4. Create the key and copy the plaintext lm_sys_… value from the one-time reveal dialog.
  5. Set it as LUMIO_AUDIT_INGEST_KEY in apps/id's environment (see apps/id/.env.example) and redeploy apps/id.
  6. Confirm apps/id's GET /api/health now reports audit_ingest_configured=true, then verify a fresh login produces a user:login row in that user's audit log.

Rotate it like any other system key: mint a replacement, update LUMIO_AUDIT_INGEST_KEY, redeploy, then revoke the old key.

Permissions​

ActionPermission
View keyssystem-keys:read
Create a keysystem-keys:create
Revoke a keysystem-keys:delete

Dashboard entry requires admin:access. System admins implicitly hold every system-keys permission.

API​

UI actionGraphQLREST
List system keysadminSystemKeysGET /v1/admin/system-keys
Create a system keyadminCreateSystemKeyPOST /v1/admin/system-keys
Revoke a system keyadminDeleteSystemKeyDELETE /v1/admin/system-keys/\{id\}
List assignable scopesadminSystemKeyPermissionsGET /v1/admin/system-key-permissions

Tips & gotchas​

  • The plaintext key is shown once. The key card displays only the non-secret prefix afterwards; there is no way to recover the full key, so lost keys must be revoked and recreated.
  • Keys are stored as a SHA-256 hash in the api_keys table (the row is flagged is_system = true, with no owning user or account). The DB never sees the plaintext after creation.
  • System keys are one of Lumio's authenticated token contexts. See Authentication for the public auth overview.
  • Label is free-form, but putting the environment (prod, staging) in the name helps auditing later.
  • Permissions are chosen at creation time and cannot be edited afterwards - there is no update endpoint. Changing a key's scope means creating a new key and revoking the old one.
  • Revoke has no confirmation. One click deletes the key.