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 permission from the chip 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.
  • Permissions — a chip picker. The Create button stays disabled until a label is entered and at least one permission is selected.

The picker offers: events:read, events:create, chat:read, chat:write, overlays:read, overlays:create, overlays:edit, overlays:delete, connections:read, connections:create, connections:edit, connections:delete, and admin:*.

admin:* is a wildcard grant. Account roles can never carry wildcards — system keys are the one token type that legitimately does — so hand it out sparingly.

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.

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. 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.