v47

latestOpenAPI 3.0.3MIT Licenseraw.githubusercontent.com2026-08-015915132.9 KB

admin

oauth-client

Create a new custom OIDC/OAuth provider

Creates a new custom OAuth 2.0 or OIDC provider configuration. Required fields differ based on provider_type. Only available when custom OIDC/OAuth providers are enabled. For OIDC providers, the server fetches and validates the OpenID Connect discovery document from the issuer's well-known endpoint (or the provided discovery_url) at creation time. This ensures the issuer is reachable and correctly configured before the provider is stored.

post/admin/custom-providers

Request body

provider_type'oauth2' | 'oidc' required

Type of OAuth provider

identifierstring required

Unique identifier (will be prefixed with 'custom:' automatically). Cannot use reserved provider names.

namestring required

Human-readable display name

client_idstring required

OAuth client ID from the provider

client_secretstring required

OAuth client secret (will be encrypted at rest)

acceptable_client_idsstring[]

Additional acceptable client IDs for token validation

scopesstring[]

OAuth scopes to request (OIDC providers will automatically include 'openid')

pkce_enabledboolean

Enable PKCE (Proof Key for Code Exchange)

attribute_mappingobject

Map provider claims to user attributes (cannot map to protected system fields)

custom_claims_allowliststring[]

Raw IdP claim keys to copy verbatim into the user's custom_claims (e.g. groups, org_id). For OIDC providers these are read from the ID token claims (falling back to the userinfo response when no ID token is returned); for OAuth2 providers they are read from the userinfo response. Empty preserves no non-standard claims.

authorization_paramsobject

Additional authorization request parameters as string key-value pairs (cannot override reserved OAuth parameters)

enabledboolean

Whether the provider is enabled

email_optionalboolean

Whether email is optional for users from this provider

issuerstring uri

OIDC issuer URL (required for provider_type: oidc)

discovery_urlstring uri

OIDC discovery URL (optional for OIDC, defaults to {issuer}/.well-known/openid-configuration)

skip_nonce_checkboolean

Skip nonce validation for OIDC (not recommended for production)

authorization_urlstring uri

OAuth 2.0 authorization endpoint (required for provider_type: oauth2)

token_urlstring uri

OAuth 2.0 token endpoint (required for provider_type: oauth2)

userinfo_urlstring uri

OAuth 2.0 userinfo endpoint (required for provider_type: oauth2)

jwks_uristring uri

JWKS URI for token validation (optional for OAuth2)

Example request

{
  "identifier": "mycompany",
  "name": "My Company SSO",
  "scopes": [
    "email",
    "profile"
  ],
  "attribute_mapping": {
    "email": "user_email",
    "name": "full_name"
  },
  "custom_claims_allowlist": [
    "groups",
    "org_id"
  ],
  "authorization_params": {
    "prompt": "consent"
  },
  "issuer": "https://accounts.google.com",
  "authorization_url": "https://provider.com/oauth/authorize",
  "token_url": "https://provider.com/oauth/token",
  "userinfo_url": "https://provider.com/oauth/userinfo"
}

Response

Custom OIDC/OAuth provider created successfully

idstring uuid required

Unique provider identifier

provider_type'oauth2' | 'oidc' required

Type of OAuth provider

identifierstring required

Unique identifier for the provider (must start with 'custom:' prefix)

namestring required

Human-readable name of the provider

client_idstring required

OAuth client ID

acceptable_client_idsstring[]

Additional acceptable client IDs for token validation

scopesstring[]

OAuth scopes to request (OIDC providers will automatically include 'openid')

pkce_enabledboolean

Whether PKCE (Proof Key for Code Exchange) is enabled

attribute_mappingobject

Maps provider claims to user attributes

custom_claims_allowliststring[]

Raw IdP claim keys copied verbatim into the user's custom_claims (e.g. groups, org_id). For OIDC providers these are read from the ID token claims (falling back to the userinfo response when no ID token is returned); for OAuth2 providers they are read from the userinfo response. Empty preserves no non-standard claims.

authorization_paramsobject

Additional parameters to include in authorization requests as string key-value pairs (cannot override reserved OAuth parameters)

enabledboolean

Whether the provider is enabled

email_optionalboolean

Whether email is optional for users from this provider

issuerstring uri

OIDC issuer URL (required for OIDC providers)

discovery_urlstring uri

OIDC discovery URL (optional, defaults to {issuer}/.well-known/openid-configuration)

skip_nonce_checkboolean

Skip nonce validation for OIDC (not recommended for production)

authorization_urlstring uri

OAuth 2.0 authorization endpoint (required for OAuth2 providers)

token_urlstring uri

OAuth 2.0 token endpoint (required for OAuth2 providers)

userinfo_urlstring uri

OAuth 2.0 userinfo endpoint (required for OAuth2 providers)

jwks_uristring uri

JWKS URI for token validation (optional for OAuth2 providers)

created_atstring date-time

updated_atstring date-time

Example response

{
  "identifier": "custom:mycompany",
  "name": "My Company SSO",
  "scopes": [
    "openid",
    "email",
    "profile"
  ],
  "attribute_mapping": {
    "email": "user_email",
    "name": "full_name"
  },
  "custom_claims_allowlist": [
    "groups",
    "org_id"
  ],
  "authorization_params": {
    "prompt": "consent"
  },
  "issuer": "https://accounts.google.com"
}