Authentication - SSO

Single sign-on (SAML/OIDC) login flows.

📄️ Resolve SSO Protocol for a Slug

Returns the SSO protocol ('saml' or 'oidc') configured for the given slug. Used by the login page to route the user to the correct SSO initiation endpoint. Returns the same 404 as other slug-miss paths — tenant existence is not revealed.

📄️ Get SP SAML Metadata

Return the Service Provider SAML metadata XML for the given client slug, for upload to the tenant's Identity Provider. Responds 404 when the slug has no SSO configuration.

📄️ Initiate SAML Login

Start the SP-initiated SAML flow: builds a signed authentication request and redirects the browser (302) to the tenant's Identity Provider. An optional return_url query parameter is carried in an HMAC-signed RelayState.

📄️ SAML Assertion Consumer Service

Receive and validate the SAML response posted by the IdP (form fields SAMLResponse and RelayState), provision or match the user, and redirect to the frontend with a one-time token-exchange code. Responds 400 on validation, replay, or missing-email failures.

📄️ Confirm Account Linking

Validate a pre-issued one-time link token and the user's current password to confirm linking an existing account to SSO. Responds 401 for a wrong password, 404 for an expired or unknown token, and 503 when the token store is unavailable.

📄️ SAML Single Logout Service

Receives IdP-initiated LogoutRequest / LogoutResponse messages (HTTP-Redirect binding), validates them, and answers the IdP or redirects the browser back to the login page.

📄️ Initiate OIDC Login

Start the OIDC authorization-code flow with PKCE: generates state, nonce, and code verifier, stores them server-side (with a cookie fallback), and redirects the browser (302) to the tenant's OIDC provider.

📄️ Handle OIDC Callback

Handle the OIDC provider redirect: verifies the state parameter, exchanges the authorization code with PKCE, validates the ID token, provisions or matches the user, and redirects to the frontend with a one-time token-exchange code. Responds 400 for state errors, 401 for an invalid ID token, and 502 when the token exchange fails.

📄️ Exchange SSO Code for Access Token

Redeem the one-time code issued at the end of an SSO login for a JWT access token. The code expires after 60 seconds and is deleted on first use. Responds 400 for an invalid or expired code and 503 when the code store is unavailable. Rate-limited to 20 requests per minute.