Skip to main content

OAuth Clients

The OAuth Clients view is where operators register third-party applications that can obtain Lumio access tokens on behalf of users via standard OAuth 2.0 flows - for example, a native desktop overlay tool using PKCE, or a server-to-server integration using client-credentials. It is not the surface for configuring Lumio's own OAuth to Twitch / YouTube / etc. (that is System Connections).

Where to find it​

Admin sidebar → OAuth Clients (/oauth-clients).

Quick start​

  1. Open Admin → OAuth Clients.
  2. Click Create Client.
  3. Fill in the Name, pick the Client Type, paste one redirect URI per line, and select scopes and grant types.
  4. A one-time panel reveals the Client ID and Client Secret - copy and store the secret immediately. It is never shown again.
  5. The new client appears in the list with its type, scopes, and an Enabled badge.

Detailed walkthrough​

Clients list​

Clients render as cards, not table rows, above a "{N} client(s)" counter. Each card surfaces:

  • Name - display name.
  • Enabled / Disabled badge and a Client Type badge (public - mobile / desktop using PKCE, no secret - or confidential - server-side, uses secret).
  • Client ID - monospace.
  • Scopes - the granted scopes, as chips.

Redirect URIs and grant types are stored on the client and returned by the API, but the card does not render them.

Card actions:

  • Enable / Disable - flips the client's active flag via PATCH. Gated on oauth-clients:edit. Disabled clients cannot complete OAuth flows but existing tokens keep working until expiry.
  • Delete - hard-deletes the client registration, with no confirmation prompt. Gated on oauth-clients:delete.

Create form​

Clicking Create Client (gated on oauth-clients:create) opens an inline card form, not a dialog:

  • Name - free text (placeholder: "My Application"). Required.
  • Client Type - dropdown: Confidential (default) or Public.
  • Redirect URIs - newline-separated textarea (placeholder shows https://example.com/callback and https://localhost:3000/callback).
  • Scopes - chip picker offering read, write, overlays:read, overlays:create, overlays:edit, overlays:delete, events:read, events:create, chat:read, chat:write, and admin:*.
  • Grant Types - chip picker offering authorization_code (preselected), client_credentials, and refresh_token.

Secret reveal​

After creation the UI shows a warning-styled panel:

  • Title: "Client Created - Save Your Credentials".
  • Body: "The client secret will only be shown once. Copy it now and store it securely."
  • The Client ID and Client Secret, plus Copy Secret and Dismiss buttons.

The client card never shows the secret again. Confidential clients that lose their secret need a delete + recreate.

Common scenarios​

  • Native desktop overlay app - Create a client with Client Type Public and a PKCE-compatible redirect (e.g. http://127.0.0.1:PORT/callback for local loopback, or a custom URL scheme).
  • Internal back-office integration - Create a confidential client with client_credentials grant type and a dedicated scope set.
  • Temporarily suspend a buggy third-party app - Disable the client; their refresh flows will fail, existing access tokens last until TTL.
  • Rotate a leaked secret - Delete + recreate. There is no rotate-in-place flow today.

Permissions​

ActionPermission
View OAuth clientsoauth-clients:read
Create a clientoauth-clients:create
Edit (enable / disable, update fields)oauth-clients:edit
Delete a clientoauth-clients:delete

Dashboard entry requires admin:access. System admins implicitly hold every OAuth clients permission.

API​

UI actionGraphQLREST
List clientsadminOauthClientsGET /v1/admin/oauth-clients
Get a clientadminOauthClientGET /v1/admin/oauth-clients/\{id\}
Create clientadminCreateOauthClientPOST /v1/admin/oauth-clients
Update client (fields / enabled)adminUpdateOauthClientPATCH /v1/admin/oauth-clients/\{id\}
Delete clientadminDeleteOauthClientDELETE /v1/admin/oauth-clients/\{id\}

Tips & gotchas​

  • Secrets are shown once. Copy from the reveal panel - there is no way to recover a lost secret, only delete + recreate.
  • The Enable / Disable action is reversible. Delete is not, and it asks for no confirmation.
  • Redirect URIs are matched exactly. https://example.com/callback and https://example.com/callback/ are different registrations.
  • Public clients should never have the client_credentials grant type. The form does not stop you from selecting it - apply the rule yourself.
  • Do not confuse this with System Connections: that page holds Lumio's OAuth credentials against Twitch / YouTube / etc.; this page holds credentials that third-party apps use against Lumio.