Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt

Use this file to discover all available pages before exploring further.

KaireonAI supports both SAML 2.0 and OpenID Connect (OIDC) for enterprise single sign-on. SSO configuration is per-tenant.

​
GET /api/v1/sso

Get the SSO configuration for the tenant. Sensitive fields (client secrets, SAML certificates) are redacted. Admin only.

​
Response — Not Configured

{ "configured": false, "provider": "none" }

​
Response — Configured

{
  "configured": true,
  "provider": "oidc",
  "enabled": true,
  "samlEntityId": null,
  "samlSsoUrl": null,
  "samlAcsUrl": null,
  "oidcIssuer": "https://accounts.google.com",
  "oidcClientId": "1234567890.apps.googleusercontent.com",
  "oidcScopes": "openid email profile",
  "defaultRole": "viewer",
  "allowedDomains": ["example.com"],
  "autoProvision": true,
  "enforceForAllUsers": false
}

​
POST /api/v1/sso

Configure SSO or generate an auth URL. Admin only.

​
Actions

​
configure — Save SSO configuration

{
  "action": "configure",
  "config": {
    "provider": "oidc",
    "enabled": true,
    "oidcIssuer": "https://accounts.google.com",
    "oidcClientId": "1234567890.apps.googleusercontent.com",
    "oidcClientSecret": "GOCSPX-...",
    "oidcScopes": "openid email profile",
    "defaultRole": "viewer",
    "allowedDomains": ["example.com"],
    "autoProvision": true,
    "enforceForAllUsers": false
  }
}
Response: 
{ "success": true, "message": "SSO configuration updated" }

​
get_auth_url — Generate an OIDC authorization URL

{
  "action": "get_auth_url",
  "state": "random-state-value",
  "redirectUri": "https://app.example.com/callback"
}
Response: 
{ "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=..." }

​
GET /api/v1/sso/callback

OIDC authorization code callback. This endpoint is called by the identity provider after the user authenticates. It exchanges the authorization code for tokens, verifies the ID token signature via JWKS, and provisions or logs in the user.

​
Query Parameters

ParameterTypeRequiredDescription
codestringYesAuthorization code from the IdP
statestringYesState parameter containing tenantId:nonce. The tenant is extracted exclusively from this parameter for security.
The state parameter is mandatory. The tenant ID is extracted only from the state parameter (format: tenantId:nonce). There is no fallback to a tenant query parameter — this prevents session fixation attacks where an attacker could redirect a user through SSO with a manipulated tenant ID.
The OIDC client_id must be configured in the SSO settings. If oidcClientId is missing, the callback will return 400 Bad Request because the token audience cannot be verified, which would allow cross-client token reuse.

​
Response

{
  "userId": "clx...",
  "email": "john@example.com",
  "name": "John Smith",
  "created": false,
  "provider": "oidc"
}

​
POST /api/v1/sso/callback

SAML POST binding (Assertion Consumer Service). Receives the SAML response from the identity provider, validates the assertion, and provisions or logs in the user.

​
Request Body (form-encoded or JSON)

FieldTypeRequiredDescription
SAMLResponsestringYesBase64-encoded SAML response
RelayStatestringYesTenant ID. The tenant is extracted exclusively from RelayState for security — there is no fallback to query parameters.

​
Response

{
  "userId": "clx...",
  "email": "john@example.com",
  "name": "John Smith",
  "created": true,
  "provider": "saml"
}

​
Security

  • OIDC ID tokens are verified using JWKS public key discovery
  • Issuer, audience, and expiration are validated
  • SAML assertions are signature-verified against the configured certificate
  • SSO callbacks are rate limited to 30 requests/min