Skip to main content

OAuth Clients

This admin API manages OAuth 2.0 and OpenID Connect client applications within your organization. Use it to create, update, enable/disable, and delete clients, rotate client secrets, and set the scopes each client is allowed to request.

GET    /orgs/{orgId}/api/v1/admin/clients
POST   /orgs/{orgId}/api/v1/admin/clients
GET    /orgs/{orgId}/api/v1/admin/clients/{clientId}
PUT    /orgs/{orgId}/api/v1/admin/clients/{clientId}
PATCH  /orgs/{orgId}/api/v1/admin/clients/{clientId}
DELETE /orgs/{orgId}/api/v1/admin/clients/{clientId}
POST   /orgs/{orgId}/api/v1/admin/clients/{clientId}/rotate-secret
POST   /orgs/{orgId}/api/v1/admin/clients/{clientId}/enable
POST   /orgs/{orgId}/api/v1/admin/clients/{clientId}/disable
GET    /orgs/{orgId}/api/v1/admin/clients/{clientId}/scopes
PUT    /orgs/{orgId}/api/v1/admin/clients/{clientId}/scopes

Authentication​

All client management endpoints require a valid admin API key or a Bearer token issued to a user with the settings.manage permission.

The Client Object​

Client Object
{
  "id": "01JF3KABCDE...",
  "name": "My Application",
  "clientId": "client_abc123...",
  "redirectUris": ["https://app.example.com/callback"],
  "scopes": ["openid", "profile", "email"],
  "grantTypes": ["authorization_code", "refresh_token"],
  "isPublic": false,
  "pkceRequired": true,
  "isActive": true,
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-03-01T08:00:00Z"
}

List Clients​

List All Clients
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/clients?page=1&limit=50" \
  -H "Authorization: ApiKey lmk_abc123"

Query Parameters​

ParameterDescription
pagePage number (default: 1)
limitResults per page (default: 20, max: 100)
searchFilter by name or client ID
isActiveFilter by active status (true/false)

Create Client​

Redirect URIs must be valid HTTPS URLs. localhost is allowed for development.

Create a Client
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/clients \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Application",
    "redirectUris": ["https://app.example.com/callback"],
    "scopes": ["openid", "profile", "email"],
    "grantTypes": ["authorization_code", "refresh_token"],
    "isConfidential": true,
    "requiresPkce": true
  }'
201 Created
{
  "data": {
    "data": {
      "id": "01JF3KABCDE...",
      "clientId": "client_abc123...",
      "secret": "raw_secret_only_shown_once",
      "name": "My Application",
      "_note": "Store the secret securely. It will not be shown again."
    }
  }
}
warning

secret is returned only once at creation time. Store it securely — it cannot be retrieved again.

Create Parameters​

FieldTypeDescription
namestringRequired. Display name
redirectUrisarrayAllowed redirect URIs (must be valid HTTPS URLs)
scopesarrayAllowed scopes (default: openid profile email)
grantTypesarrayAllowed grant types (default: authorization_code refresh_token)
isConfidentialbooleantrue for server-side apps, false for SPAs (default: true)
requiresPkcebooleanRequire PKCE for authorization code flow (default: true)

Update Client​

Use PUT to replace all fields; PATCH for partial updates.

Update a Client
curl -X PATCH https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/clients/01JF3KABCDE... \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Application v2",
    "redirectUris": [
      "https://app.example.com/callback",
      "https://app.example.com/auth/callback"
    ]
  }'

Enable / Disable Client​

Disabling a client blocks new token requests but does not revoke existing tokens.

Disable a Client
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/clients/01JF3KABCDE.../disable \
  -H "Authorization: ApiKey lmk_abc123"
Response
{
  "data": {
    "data": { "id": "01JF3KABCDE...", "isActive": false }
  }
}
Enable a Client
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/clients/01JF3KABCDE.../enable \
  -H "Authorization: ApiKey lmk_abc123"

Rotate Client Secret​

Rotate Secret
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/clients/01JF3KABCDE.../rotate-secret \
  -H "Authorization: ApiKey lmk_abc123"
Response
{
  "data": {
    "data": { "secret": "new_secret_only_shown_once" }
  }
}

Manage Client Scopes​

Get Client Scopes​

Get Client Scopes
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/clients/01JF3KABCDE.../scopes" \
  -H "Authorization: ApiKey lmk_abc123"
Response
{
  "data": {
    "data": { "scopes": ["openid", "profile", "email", "read:reports"] }
  }
}

Set Client Scopes​

Replaces all allowed scopes for the client.

Set Client Scopes
curl -X PUT https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/clients/01JF3KABCDE.../scopes \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["openid", "profile", "email", "read:reports", "write:reports"]}'

Delete Client​

Delete a Client
curl -X DELETE https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/clients/01JF3KABCDE... \
  -H "Authorization: ApiKey lmk_abc123"

Returns 200 on success. Deleting a client does not revoke existing access tokens — revoke tokens first if needed.