POST /api/v1/auth/register
Register a new user account. Creates a user, a personal playground tenant, and sends a verification email. 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):
{
"message": "If this email is available, a verification link has been sent."
}
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-based). Supports setup, enable, verify, and disable actions.
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 |
