Authentication

Overview

KaireonAI supports two authentication methods:

Google OAuth — one-click sign-in with your Google account
Email & Password — register with email, verify, then sign in

Both methods create a personal workspace where you have full admin access. Each user gets their own isolated tenant — your data is completely separate from other users.

Playground Registration

The hosted playground at playground.kaireonai.com offers self-service registration.

Visit playground.kaireonai.com/register
Click Sign up with Google
Select your Google account
You’re signed in — no email verification needed

Google OAuth users are automatically verified and receive a welcome email.

Visit playground.kaireonai.com/register
Fill in your name, email, and password
Optionally provide a Tenant name — if set, the new tenant is created with this display name. Leave it blank to default to "{Your Name}'s Workspace".
Click Create Account
Check your inbox for a verification email from support@kaireonai.com
Click the Verify Email link
Sign in at playground.kaireonai.com/login

Password requirements: minimum 8 characters, at least 1 uppercase letter, at least 1 number.

The tenant name only controls the display label in the studio header and approval audit log — it does not affect tenant isolation, billing, or API routing.

After Registration

New users land on the platform as an admin of their personal workspace. An onboarding banner guides you to load sample data — go to Settings → Sample Data and load a dataset pack (e.g., Retail Rewards) to explore the full platform. You have full access to create Offers, schemas, Decision Flows, pipelines, and everything else.

Playground Limits

Decision Quota

Each playground workspace has a 5,000 lifetime decision limit. Decisions are counted when:

The Recommend API generates impressions
Batch pipeline runs produce decisions
Journey triggers fire automated decisions

Read operations and outcome recording (Respond API) do not count toward the limit. When the limit is reached, you’ll see a banner with options to continue.

Workspace Reset

If you’ve used up your decisions or want to start fresh, go to Settings → Reset Workspace. This deletes all data in your workspace (offers, flows, schemas, interaction history, etc.) and resets your decision counter to 0. Your account and workspace remain intact.

No Entity Limits

There are no limits on creating entities (Offers, schemas, Decision Flows, pipelines, etc.) in the playground. The only constraint is the 5,000 decision cap.

The playground is a shared environment. Do not use production data or real customer information. For production use, self-host the platform or email support@kaireonai.com for a managed SaaS plan.

Data Isolation

Every user’s data is completely isolated in their own tenant:

Separate data storage — offers, schemas, pipelines, interaction history, and all other data is scoped to your tenant
No cross-tenant access — API routes enforce tenant boundaries on every request
Independent models — scoring models and experiments are trained only on your tenant’s data
Isolated Decision Flows — your flows, rules, and configurations are private to your workspace

Self-Hosted Authentication

When self-hosting KaireonAI, authentication is configured via environment variables:

Variable	Description	Required
`NEXTAUTH_SECRET`	Random secret for signing JWT sessions	Yes
`NEXTAUTH_URL`	Public URL of your deployment (e.g., `https://your-domain.com`)	Yes
`GOOGLE_CLIENT_ID`	Google OAuth client ID	For Google sign-in
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret	For Google sign-in
`SES_FROM_EMAIL`	Sender email for transactional emails	For email registration
`AWS_REGION`	AWS region for SES	For email registration

Self-hosted instances have no decision limits — the 5,000 cap only applies to the hosted playground.

Google OAuth Setup

To enable Google sign-in on your self-hosted instance:

Create OAuth credentials

Go to Google Cloud Console, create an OAuth 2.0 Client ID for a Web application.

Configure redirect URIs

Add your deployment URL as an authorized redirect URI:

https://your-domain.com/api/auth/callback/google

For local development, also add:

http://localhost:3000/api/auth/callback/google

Set environment variables

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your-secret

Email Verification Setup

Email verification requires an email sending service. The platform uses AWS SES by default:

Verify your domain in SES

Add DKIM records and verify your sending domain in the AWS SES console.

Set environment variables

SES_FROM_EMAIL=support@your-domain.com
AWS_REGION=us-east-1

If running on AWS (App Runner, ECS, EC2), the platform uses the IAM instance role for SES — no credentials needed. For other environments, configure the standard AWS env vars AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Seed Admin User

For self-hosted deployments, create the initial admin user with the seed script:

npx tsx prisma/seed.ts

This creates a default tenant and an admin user (admin@kaireonai.com / admin123). Change the password immediately after first login.

User Roles

Role	Permissions
Admin	Full access — manage users, settings, all modules
Editor	Create and modify offers, rules, flows, pipelines
Viewer	Read-only access to all modules

New playground registrations receive the admin role on their personal workspace. Self-hosted admins can manage roles via the database.

Session Invalidation

KaireonAI sessions are stateless JWTs (~30-minute lifetime, auto-refreshed). Deleting a user, disabling a user, or changing a user’s role invalidates their live sessions within roughly 30 seconds — not the full JWT lifetime. Each user row carries a tokenVersion (bumped on role change, account disable/enable, or MFA enrollment) and a disabled flag. Every protected API route re-validates these against the database at the authorization choke points (requireTenant() and requireRole()), not just at sign-in — a request carrying a JWT whose embedded tokenVersion no longer matches the live row, or whose user is now disabled, is rejected even though the JWT signature itself is still valid and unexpired:

{
  "title": "Unauthorized",
  "detail": "Your session is no longer valid (account changed, disabled, or removed). Please sign in again."
}

A short (30-second) in-memory cache bounds this to roughly one database read per user per window rather than a database round trip on every request, and the check fails closed — if the liveness lookup itself errors, the session is rejected rather than trusted. Previously, none of this existed: a deleted, disabled, or role-downgraded user’s session kept working for up to the full ~30-minute JWT lifetime.

API Key Management

API keys provide programmatic access to the KaireonAI REST API without user sessions. They are ideal for server-to-server integrations, CI/CD pipelines, and MCP connections.

Key scopes: data plane vs control plane

The REST API is split into two planes, and a key’s scopes array (set at creation, immutable afterwards) determines which it can reach:

Data plane — exactly POST /api/v1/recommend, POST /api/v1/respond, POST /api/v1/respond/bulk, and POST /api/v1/capture (a legacy alias of /respond). A key minted with no scopes ([], the default) is data-plane-only.
Control plane — everything else (all management CRUD: schemas, offers, categories, channels, creatives, decision flows, decisioning gates, connectors, pipelines, segments, models, reports, settings, API keys, …). Requires a first-party session, an MCP connection, or a key minted with scopes: ["control-plane"] (admin-only to mint).
scopes: ["scim"] mints a SCIM provisioning key for /api/v1/scim/v2/* (used with Authorization: Bearer <key>).

A key without the required access gets 403 with

{ "title": "Forbidden", "detail": "This API key is scoped to the data plane (recommend / respond). Management endpoints require a first-party session, an MCP connection, or an API key minted with the \"control-plane\" scope." }

Migration note: as of the control-plane / data-plane split, existing API keys with no explicit scopes are now data-plane-only (recommend/respond). To manage resources programmatically, mint a new key with the control-plane scope — and keep it internal; never embed it in client apps.

The master/internal server key (API_KEY env var) and cron/webhook secrets are internal infrastructure, not customer keys, and are unaffected.

Creating an API Key

Endpoint: POST /api/v1/api-keys Required role: Admin

curl -X POST https://your-domain.com/api/v1/api-keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CI Pipeline", "expiresAt": "2027-01-01T00:00:00Z" }'

Response:

{
  "id": "clx...",
  "name": "CI Pipeline",
  "key": "krn_a1b2c3d4e5f6...",
  "prefix": "krn_a1b2c3d4",
  "expiresAt": "2027-01-01T00:00:00.000Z",
  "createdAt": "2026-03-16T12:00:00.000Z",
  "warning": "Store this key securely. It will not be shown again."
}

The raw API key is returned only at creation time. Store it securely — it cannot be retrieved later. Only the prefix is shown in subsequent listings.

Listing API Keys

Endpoint: GET /api/v1/api-keys Required role: Admin Returns all active (non-revoked) keys for the tenant, showing prefix, name, last used date, and expiration.

Revoking an API Key

Endpoint: DELETE /api/v1/api-keys?id=<key-id> Required role: Admin Soft-revokes the key immediately. Revoked keys cannot authenticate. Optionally include a reason in the request body.

Using an API Key

Include the key in the X-API-Key header (there is no Authorization: Bearer scheme for API keys — a Bearer token is rejected with 401; the only exception is SCIM keys on /scim/v2/*):

curl -X POST https://your-domain.com/api/v1/recommend \
  -H "X-API-Key: krn_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "cust-123" }'

API keys are hashed with HMAC using the API_KEY_PEPPER environment variable before storage. Set this variable in production for security.

OAuth 2.0 Client Credentials

KaireonAI supports the OAuth 2.0 client credentials grant (RFC 6749 Section 4.4) for machine-to-machine authentication. This is the recommended approach for production integrations.

Registering an OAuth Client

Endpoint: POST /api/v1/oauth/clients Required role: Admin

curl -X POST https://your-domain.com/api/v1/oauth/clients \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Data Pipeline Service", "scopes": ["read", "write"] }'

Response:

{
  "id": "clx...",
  "name": "Data Pipeline Service",
  "clientId": "kci_abc123...",
  "clientSecret": "kcs_def456...",
  "scopes": ["read", "write"],
  "createdAt": "2026-03-16T12:00:00.000Z",
  "warning": "Store the client secret securely. It will not be shown again."
}

Available scopes: read, write, admin

Obtaining an Access Token

Endpoint: POST /api/v1/oauth/token Accepts form-encoded or JSON body:

curl -X POST https://your-domain.com/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=kci_abc123...&client_secret=kcs_def456..."

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Access tokens expire after 1 hour. Request a new token when the current one expires.

Listing and Revoking Clients

List: GET /api/v1/oauth/clients (admin only)
Revoke: DELETE /api/v1/oauth/clients?id=<client-id> (admin only)

Revoking a client immediately invalidates all future token requests for that client. Existing tokens remain valid until they expire.

Rate Limiting

The token endpoint is rate-limited to 20 requests per minute per client ID (or per IP when the client ID is absent). When Redis is unavailable, the rate limiter fails closed to prevent brute-force attacks.

SCIM User Provisioning

KaireonAI implements SCIM 2.0 (System for Cross-domain Identity Management) for automated user provisioning from identity providers like Okta, Azure AD, and OneLogin.

Base URL

https://your-domain.com/api/v1/scim/v2/

Supported Operations

Endpoint	Method	Description
`/Users`	GET	List users (paginated with `startIndex` and `count`)
`/Users`	POST	Create a user from a SCIM resource
`/Users/:id`	GET	Get a single user
`/Users/:id`	PUT	Replace a user resource (update name, email, active status)
`/Users/:id`	DELETE	Deactivate a user (soft delete)

SCIM endpoints require a bearer token validated by requireSCIMAuth. Configure this in your identity provider with the SCIM bearer token from your KaireonAI tenant settings.

User Lifecycle

Create (POST /Users) — Creates a new user in the tenant with member role. Requires userName (email).
Update (PUT /Users/:id) — Updates name and email. Set active: false to deactivate.
Delete (DELETE /Users/:id) — Soft-deactivates the user (sets lockedUntil to a far-future date). Does not hard-delete.

Example: Create a User

curl -X POST https://your-domain.com/api/v1/scim/v2/Users \
  -H "Authorization: Bearer <scim-token>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane.doe@example.com",
    "name": { "givenName": "Jane", "familyName": "Doe" },
    "displayName": "Jane Doe",
    "active": true
  }'

All SCIM operations are audit-logged with userId: "scim" for traceability. SCIM users are scoped to the authenticated tenant — no cross-tenant access is possible.

Security

JWT sessions — 30-minute expiry, auto-refreshed
Account lockout — 5 failed login attempts locks the account for 15 minutes
Email verification — required for email/password registration
Rate limiting — registration endpoint: 5 attempts per IP per hour; OAuth token endpoint: 20 per minute per client
CSRF protection — all state-changing API requests require X-Requested-With header
Tenant isolation — all data access is scoped to the authenticated user’s tenant
API key hashing — keys are HMAC-hashed with a pepper before storage
OAuth secret hashing — client secrets are hashed before storage; timing-safe comparison prevents timing attacks
Audit logging — all auth events (login, token grants, key creation/revocation, SCIM operations) are logged

​Overview

​Playground Registration

​Sign Up with Google

​Sign Up with Email

​After Registration

​Playground Limits

​Decision Quota

​Workspace Reset

​No Entity Limits

​Data Isolation

​Self-Hosted Authentication

​Google OAuth Setup

​Email Verification Setup

​Seed Admin User

​User Roles

​Session Invalidation

​API Key Management

​Key scopes: data plane vs control plane

​Creating an API Key

​Listing API Keys

​Revoking an API Key

​Using an API Key

​OAuth 2.0 Client Credentials

​Registering an OAuth Client

​Obtaining an Access Token

​Listing and Revoking Clients

​Rate Limiting

​SCIM User Provisioning

​Base URL

​Supported Operations

​Authentication

​User Lifecycle

​Example: Create a User

​Security

Overview

Playground Registration

Sign Up with Google

Sign Up with Email

After Registration

Playground Limits

Decision Quota

Workspace Reset

No Entity Limits

Data Isolation

Self-Hosted Authentication

Google OAuth Setup

Email Verification Setup

Seed Admin User

User Roles

Session Invalidation

API Key Management

Key scopes: data plane vs control plane

Creating an API Key

Listing API Keys

Revoking an API Key

Using an API Key

OAuth 2.0 Client Credentials

Registering an OAuth Client

Obtaining an Access Token

Listing and Revoking Clients

Rate Limiting

SCIM User Provisioning

Base URL

Supported Operations

Authentication

User Lifecycle

Example: Create a User

Security