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.
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 (prevents email enumeration). Source: src/app/api/v1/auth/register/route.ts:50, 131, 225.
{
"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.
{
"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.
{
"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.
{
"verified": true,
"method": "totp"
}
disable — Disable MFA (requires valid TOTP token).
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 |
Response
{
"id": "key_001",
"name": "Production API Key",
"key": "krn_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef12345678",
"prefix": "krn_a1b2c3d4",
"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 |
