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 submit.
  5. 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 a table with:

  • Label — human-friendly name given at creation.
  • Permissions — scoped permission list (array of resource:action).
  • Created — creation timestamp.
  • Last used — last-seen timestamp or "—" if unused.
  • Revoke — red action button; prompts and deletes.

Create System API Key dialog​

Fields:

  • Label — e.g. Twitch Bot Key.

Submit invokes POST /api/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. Any in-flight 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 — sort by "Last used"; revoke keys with no recent usage.
  • Investigate a suspicious request — match the audit log entries to the key's Label (system key usage is attributed in the audit log).

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\}

Tips & gotchas​

  • The plaintext key is shown once. There is no lookup, no partial display, and no regeneration — lost keys must be deleted and recreated.
  • Keys are stored as an Argon2id hash in the system_keys table. The DB never sees the plaintext after creation.
  • System keys are one of Lumio's five auth types (alongside JWT, User API Key, Popout Token, and Anonymous). See CLAUDE.md → Auth for the full list.
  • Label is free-form, but putting the environment (prod, staging) in the name helps auditing later.
  • There is no per-key scope editor in the UI today — permission scoping is set server-side by the Rust service that provisions each key.
  • System Connections — Lumio's outbound OAuth credentials (shares the same page)
  • OAuth Clients — public OAuth apps for third-party users
  • Audit Log — records api_key.created and api_key.revoked events