SSO API

The SSO API covers three things: provider discovery for the login page, the browser-redirect single sign-on flow (OAuth2 / OIDC, SAML2, CAS), and the user unlinking their own SSO identity. Provider CRUD belongs to the admin surface under /api/v1/admin/sso.

Endpoints

1. List enabled providers

GET /api/v1/sso/providers

Used by the login page to render SSO buttons. Only is_enabled=true providers are returned, and no sensitive configuration is included.

200 OK:

{
  "code": 0,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "github",
      "display_name": "GitHub",
      "icon_url": "https://cdn.example.com/github.svg",
      "button_text": "Continue with GitHub",
      "protocol": "oauth2"
    }
  ],
  "msg": "success"
}

2. Begin SSO login

GET /api/v1/sso/login/{provider_name}

Query parameters

Behaviour:

1. Validates that the provider exists and is enabled; otherwise it redirects to {frontend}/sso-callback?error=sso_provider_not_found.
2. Generates a random state (the session_id, secrets.token_urlsafe(32)) and creates an SSO session that expires after 10 minutes, storing the PKCE code_verifier / nonce (OAuth2, OIDC) or RelayState.
3. Builds the callback URL from the backend origin: {backend}/api/v1/sso/callback/{provider_name}.
4. Returns 307 Temporary Redirect to the identity provider's authorization URL.

Failure redirect:

{frontend}/sso-callback?error=<error_code>&redirect=<path>

3. Identity-provider callback

GET /api/v1/sso/callback/{provider_name}

The identity provider redirects the browser here after the user authenticates. Parameters differ by protocol:

Success → the browser is redirected to:

{frontend}/sso-callback?token=<access_token>&redirect=<path>

token is a standard JWT access token (lifetime controlled by the session_timeout_days site setting, default 7 days). When single_session is enabled the server records the session so older tokens are invalidated. The SSO session is deleted immediately after success.

Failure → redirect to {frontend}/sso-callback?error=<error_code>&redirect=<path>. Common error values:

4. Unlink your own SSO connection

DELETE /api/v1/sso/connections/{connection_id}

Path parameters

Only connections belonging to the caller can be operated on. If the account has no password and this is its last SSO connection, deletion is refused (the account would become unreachable).

The caller's connection list is available from the sso_connections field of GET /api/v1/users/me; see the Users API.

200 OK:

{
  "code": 0,
  "data": null,
  "msg": "success"
}

Errors:

5. Admin: provider configuration

The following endpoints are mounted under /api/v1/admin/sso.

5.1 List all providers

GET /api/v1/admin/sso/providers

Requires admin:sso:read. Returns all providers (including is_enabled=false) with their full configuration.

config fields by protocol:

5.2 Create a provider

POST /api/v1/admin/sso/providers

Requires admin:sso:update. Body fields match the table above (name, protocol, display_name, config required; attribute_mapping defaults to {}, is_enabled to true, allow_signup to true, require_approval to false).

curl -X POST "https://your-domain.com/api/v1/admin/sso/providers" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "protocol": "oauth2",
    "display_name": "GitHub",
    "config": {"client_id": "...", "client_secret": "...", "authorization_url": "https://github.com/login/oauth/authorize", "token_url": "https://github.com/login/oauth/access_token", "userinfo_url": "https://api.github.com/user", "scopes": ["read:user", "user:email"]},
    "attribute_mapping": {"email": "email", "username": "login"},
    "is_enabled": true,
    "allow_signup": true,
    "require_approval": false
  }'

Errors:

5.3 Update a provider

PUT /api/v1/admin/sso/providers/{provider_id}

Requires admin:sso:update. Every field is optional and only the supplied ones are applied; a conflicting name also returns 6305.

Errors:

5.4 Delete a provider

DELETE /api/v1/admin/sso/providers/{provider_id}

Requires admin:sso:update. Deleting a provider also removes its configuration.

Errors: 400 + 6300 (sso_provider_not_found).

5.5 Test a provider

POST /api/v1/admin/sso/providers/{provider_id}/test

Requires admin:sso:update. Attempts to build an authorization URL with a test state and callback to validate the configuration.

200 OK:

{
  "code": 0,
  "data": {
    "status": "success",
    "message": "SSO provider configuration is valid",
    "authorization_url": "https://github.com/login/oauth/authorize?client_id=..."
  },
  "msg": "success"
}

When the configuration is invalid the response is still 200 OK, but data.status is "error", message is a generic error string, and authorization_url is absent.

5.6 Unlink any user's connection

DELETE /api/v1/admin/sso/connections/{connection_id}

Requires admin:sso:update. Semantics match self-service unlinking, but any user's connection may be targeted; the "no password and only sign-in method" protection still applies.

Errors:

Error handling

The login/callback flow does not use the unified envelope; failures arrive as the error parameter on the frontend's /sso-callback: sso_provider_not_found, sso_session_expired, sso_login_failed, pending_approval, inactive.

Related

• Authentication API — password login, JWT tokens, and TOTP two-factor verification
• SSO configuration — per-protocol settings and attribute mapping
• Users API — the sso_connections field on a user profile
• Error Handling — recover by HTTP status and business error code