> ## 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.
# Authentication
> User registration, email verification, MFA (TOTP + backup codes), API key management, and SSO configuration (OIDC; SAML on roadmap).
## POST /api/v1/auth/register
Register a new user account. Creates a user, a personal playground tenant, and a default API key. Auto-verifies the email — no separate verification email is sent on the playground build. Rate limited to 5 requests per IP per hour.
### Request Body
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------------------------------------- |
| `name` | string | Yes | Full name (max 100 chars) |
| `email` | string | Yes | Email address (max 255 chars) |
| `password` | string | Yes | Password (8-128 chars, must contain uppercase letter and number) |
### Response
Always returns the same generic message regardless of whether the email already exists, to prevent email enumeration.
```json theme={null}
{
"message": "Account created. You can now sign in."
}
```
***
## GET /api/v1/auth/verify
Verify a user's email address via the link sent during registration. Redirects to the login page.
### Query Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------ |
| `token` | string | Yes | Verification token |
| `email` | string | Yes | Email address |
### Redirect Outcomes
| Redirect | Meaning |
| ---------------------------- | -------------------------------- |
| `/login?verified=true` | Email verified successfully |
| `/login?error=invalid-token` | Token not found |
| `/login?error=expired-token` | Token expired (24h limit) |
| `/login?error=invalid-link` | Missing token or email parameter |
***
## POST /api/v1/auth/mfa
Manage multi-factor authentication (TOTP, RFC 6238). Supports `setup`, `enable`, `verify`, and `disable` actions.
**Enforcement status.** The MFA endpoints described below are implemented
and functional — secrets are encrypted at rest, backup codes are one-way
hashed, verification is timing-safe and rate-limited. **Session-level
enforcement in middleware is staged but not yet active**: `session.mfaVerified`
is hardcoded to `false` today, so a successful `verify` call does not yet
gate protected routes at the middleware layer. Wiring the verify response
into the session is the remaining work. Callers that want to require MFA
can check the `verified` response themselves until enforcement ships.
### Request Body
| Field | Type | Required | Description |
| -------- | ------ | ----------- | ----------------------------------------------------------------------------------- |
| `action` | string | Yes | `"setup"`, `"enable"`, `"verify"`, or `"disable"` |
| `token` | string | Conditional | 6-digit TOTP code or 8-character backup code (required for enable, verify, disable) |
### Actions
**`setup`** -- Generate a TOTP secret and backup codes. MFA is not yet active.
```json theme={null}
{
"otpauthUrl": "otpauth://totp/KaireonAI:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=KaireonAI",
"backupCodes": ["A1B2C3D4", "E5F6G7H8", "I9J0K1L2", "M3N4O5P6", "Q7R8S9T0", "U1V2W3X4", "Y5Z6A7B8", "C9D0E1F2"]
}
```
**`enable`** -- Verify a TOTP token to activate MFA. Returns fresh backup codes.
```json theme={null}
{
"enabled": true,
"backupCodes": ["A1B2C3D4", "..."]
}
```
Store backup codes securely. They are only shown at setup/enable time and cannot be retrieved later.
**`verify`** -- Verify a TOTP token or backup code during login. Rate limited to 3 attempts per 60 seconds.
```json theme={null}
{
"verified": true,
"method": "totp"
}
```
**`disable`** -- Disable MFA (requires valid TOTP token).
```json theme={null}
{
"disabled": true
}
```
***
## API Keys
### POST /api/v1/api-keys
Generate a new API key. Admin only.
| Field | Type | Required | Description |
| ----------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | No | Key name. Auto-generated if omitted |
| `expiresAt` | string | No | ISO expiration date |
| `scopes` | string\[] | No | Permission scopes. Omit or pass `[]` for a data-plane-only key (recommend/respond); pass `["control-plane"]` for management access. See [API Keys](/api-reference/api-keys) |
Keys are **data-plane-only by default**: a key minted without scopes can call
`POST /recommend`, `POST /respond`, `POST /respond/bulk`, and `POST /capture`,
but gets `403` on management endpoints. Management access requires a key
minted with the `control-plane` scope — keep such keys internal and never
embed them in client apps. Full scope model: [API Keys](/api-reference/api-keys).
### Response
```json theme={null}
{
"id": "key_001",
"name": "Production API Key",
"key": "krn_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678",
"prefix": "krn_a1b2c3d4",
"scopes": [],
"expiresAt": null,
"createdAt": "2026-03-16T10:00:00.000Z",
"warning": "Store this key securely. It will not be shown again."
}
```
The full API key is only returned at creation time. Store it immediately -- it cannot be retrieved later.
### GET /api/v1/api-keys
List active API keys (prefix only, never the full key). Admin only.
### DELETE /api/v1/api-keys
Revoke an API key (soft delete). Admin only.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------ |
| `id` | string | Yes | Key ID (query parameter) |
***
## SSO
### GET /api/v1/sso
Get SSO configuration for the tenant. Sensitive fields are redacted. Admin only.
### POST /api/v1/sso
Configure SSO or get an auth URL.
| Field | Type | Required | Description |
| ------------- | ------ | ------------------ | --------------------------------------------------------- |
| `action` | string | Yes | `"configure"` or `"get_auth_url"` |
| `config` | object | For configure | SSO configuration (provider, SAML/OIDC settings, domains) |
| `state` | string | For get\_auth\_url | OAuth state parameter |
| `redirectUri` | string | For get\_auth\_url | Redirect URI after authentication |
### SSO Configuration Fields
| Field | Type | Description |
| -------------------- | --------- | -------------------------------------- |
| `provider` | string | `"saml"` or `"oidc"` |
| `enabled` | boolean | Enable/disable SSO |
| `samlEntityId` | string | SAML entity ID |
| `samlSsoUrl` | string | SAML SSO URL |
| `oidcIssuer` | string | OIDC issuer URL |
| `oidcClientId` | string | OIDC client ID |
| `oidcClientSecret` | string | OIDC client secret |
| `oidcScopes` | string | OIDC scopes |
| `defaultRole` | string | Default role for SSO-provisioned users |
| `allowedDomains` | string\[] | Allowed email domains |
| `autoProvision` | boolean | Auto-create users on first SSO login |
| `enforceForAllUsers` | boolean | Require SSO for all users |
***
## Roles
| Endpoint | Allowed Roles |
| --------------------- | ------------------ |
| `POST /auth/register` | Public |
| `GET /auth/verify` | Public |
| `POST /auth/mfa` | Authenticated user |
| `POST /api-keys` | admin |
| `GET /api-keys` | admin |
| `DELETE /api-keys` | admin |
| `GET /sso` | admin |
| `POST /sso` | admin |
See also: [Authentication](/governance-security/authentication)