Authentication

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.

{
  "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).

{
  "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

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.

Response

{
  "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

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

POST /api/v1/auth/register

Request Body

Response

GET /api/v1/auth/verify

Query Parameters

Redirect Outcomes

POST /api/v1/auth/mfa

Request Body

Actions

API Keys

POST /api/v1/api-keys

Response

GET /api/v1/api-keys

DELETE /api/v1/api-keys

SSO

GET /api/v1/sso

POST /api/v1/sso

SSO Configuration Fields

Roles

​POST /api/v1/auth/register

​Request Body

​Response

​GET /api/v1/auth/verify

​Query Parameters

​Redirect Outcomes

​POST /api/v1/auth/mfa

​Request Body

​Actions

​API Keys

​POST /api/v1/api-keys

​Response

​GET /api/v1/api-keys

​DELETE /api/v1/api-keys

​SSO

​GET /api/v1/sso

​POST /api/v1/sso

​SSO Configuration Fields

​Roles

POST /api/v1/auth/register

Request Body

Response

GET /api/v1/auth/verify

Query Parameters

Redirect Outcomes

POST /api/v1/auth/mfa

Request Body

Actions

API Keys

POST /api/v1/api-keys

Response

GET /api/v1/api-keys

DELETE /api/v1/api-keys

SSO

GET /api/v1/sso

POST /api/v1/sso

SSO Configuration Fields

Roles