Social Providers

GET    /orgs/{orgId}/api/v1/admin/social-providers
GET    /orgs/{orgId}/api/v1/admin/social-providers/available
GET    /orgs/{orgId}/api/v1/admin/social-providers/types
GET    /orgs/{orgId}/api/v1/admin/social-providers/callback-urls
GET    /orgs/{orgId}/api/v1/admin/social-providers/{providerId}
PUT    /orgs/{orgId}/api/v1/admin/social-providers/{providerId}
PATCH  /orgs/{orgId}/api/v1/admin/social-providers/{providerId}
DELETE /orgs/{orgId}/api/v1/admin/social-providers/{providerId}
POST   /orgs/{orgId}/api/v1/admin/social-providers/{providerId}/enable
POST   /orgs/{orgId}/api/v1/admin/social-providers/{providerId}/disable
POST   /orgs/{orgId}/api/v1/admin/social-providers

Social providers allow users to sign in using their existing accounts from services like Google, GitHub, or Microsoft. The OAuth flow uses:

GET /orgs/{orgId}/api/v1/oauth/social/{provider}

Authentication

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

Social Provider Object

Social Provider Object

{
  "id": "01JF3KSP...",
  "provider": "google",
  "displayName": "Google",
  "clientId": "123456789.apps.googleusercontent.com",
  "enabled": true,
  "requestedScopes": ["openid", "profile", "email"],
  "callbackUrl": "https://app.lumoauth.dev/orgs/acme-corp/auth/social/google/callback",
  "createdAt": "2026-01-15T10:30:00Z"
}

note

clientSecret is write-only and will never be returned in responses.

List Configured Providers

List Configured Providers

curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/social-providers" \
  -H "Authorization: ApiKey lmk_abc123"

List Available Provider Types

Returns the full list of supported providers and their required configuration fields.

Get Available Provider Types

curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/social-providers/available" \
  -H "Authorization: ApiKey lmk_abc123"

Available Providers

{
  "data": {
    "data": [
      {
        "provider": "google",
        "name": "Google",
        "requiredFields": ["clientId", "clientSecret"],
        "optionalFields": ["hostedDomain"],
        "defaultScopes": ["openid", "profile", "email"]
      },
      {
        "provider": "github",
        "name": "GitHub",
        "requiredFields": ["clientId", "clientSecret"],
        "optionalFields": [],
        "defaultScopes": ["user:email", "read:user"]
      },
      {
        "provider": "microsoft",
        "name": "Microsoft",
        "requiredFields": ["clientId", "clientSecret"],
        "optionalFields": ["orgId"],
        "defaultScopes": ["openid", "profile", "email"]
      }
    ]
  }
}

Get Callback URLs

Before configuring a provider, retrieve the callback URL to register in your IdP's app settings:

Get Callback URLs

curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/social-providers/callback-urls" \
  -H "Authorization: ApiKey lmk_abc123"

Configure a Provider (Upsert)

PUT is an upsert: it creates the provider if it does not exist, or fully replaces the configuration if it does. clientId is required for both create and update via PUT.

Configure Google (PUT upsert)

curl -X PUT https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/social-providers/google \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "123456789.apps.googleusercontent.com",
    "clientSecret": "GOCSPX-...",
    "enabled": true,
    "requestedScopes": ["openid", "profile", "email"]
  }'

Returns 201 Created on creation, 200 OK on update.

Partial Update (PATCH)

curl -X PATCH https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/social-providers/google \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Enable / Disable a Provider

Enable a Provider

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/social-providers/google/enable \
  -H "Authorization: ApiKey lmk_abc123"

Disable a Provider

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/social-providers/google/disable \
  -H "Authorization: ApiKey lmk_abc123"

Create a Provider via POST

Create via POST

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/social-providers \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "displayName": "GitHub",
    "clientId": "Ov23li...",
    "clientSecret": "abc123...",
    "enabled": true
  }'

Delete a Provider

Delete a Provider

curl -X DELETE "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/social-providers/google" \
  -H "Authorization: ApiKey lmk_abc123"

Initiate Social Login Flow

Users sign in via social providers using the OAuth flow:

GET /orgs/{orgId}/api/v1/oauth/social/{provider}?redirect_uri=...&state=...

After authentication with the social provider, LumoAuth links the identity to the user's account and completes the OAuth flow.

Supported Providers

Provider	providerId	Required Fields
Google	google	clientId, clientSecret
GitHub	github	clientId, clientSecret
Microsoft	microsoft	clientId, clientSecret
Apple	apple	clientId, teamId, keyId, privateKey
Facebook	facebook	clientId, clientSecret
LinkedIn	linkedin	clientId, clientSecret
Generic OIDC	oidc	clientId, clientSecret, issuerUrl