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. Give it a Name, paste one redirect URI per line, and submit.
  4. A one-time dialog 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, grant types, and an Enabled badge.

Detailed walkthrough​

Clients table​

Each row surfaces:

  • Name — display name.
  • Client ID — UUID, monospace.
  • Client Type — public (e.g. mobile / desktop using PKCE, no secret) or confidential (server-side, uses secret).
  • Redirect URIs — list of registered callback URLs.
  • Scopes — OAuth scopes the client may request.
  • Grant Types — subset of authorization_code, refresh_token, client_credentials, password, etc.
  • Enabled / Disabled badge.

Row actions:

  • Enable / Disable — flips the client's active flag via PATCH. Disabled clients cannot complete OAuth flows but existing tokens keep working until expiry.
  • Delete — hard-deletes the client registration. Pre-existing tokens are invalidated.

Create dialog​

Fields:

  • Name — free text (placeholder: "My Application").
  • Redirect URIs — newline-separated list (placeholder shows https://example.com/callback\nhttps://localhost:3000/callback).
  • Submit — creates the client.

Secret-reveal dialog​

After creation the UI shows a warning-styled dialog:

  • Title: "Client Created — Save Your Credentials".
  • Body: "The client secret will only be shown once. Copy it now and store it securely."
  • Buttons: Copy Secret and Dismiss.

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

Common scenarios​

  • Native desktop overlay app — Create a public client with a PKCE-compatible redirect (e.g. http://127.0.0.1:PORT/callback for local loopback, or a custom URL scheme). No secret is stored.
  • 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. Enforce the "copy now" dialog — there is no way to recover a lost secret, only delete + recreate.
  • The Enable / Disable action is reversible. Delete is not.
  • Redirect URIs are matched exactly. https://example.com/callback and https://example.com/callback/ are different registrations.
  • Public clients should never have client_credentials grant type.
  • 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.