Documentation

Authentication & Security

All requests to the Kaiko API must be authenticated with an API key. This page explains how authentication works, how to keep your keys secure, and related security practices.

Never expose your API keys in client-side code or public repositories. Always use environment variables and server-side requests.

1. API Keys

Obtaining a Key

Sign in to the Kaiko Console.
Navigate to API Keys.
Click Create Key to generate a new key.

Key Format

Environment	Key Prefix	Base URL
Production	kaiko_live_xxx	https://api.kaikostudios.xyz
Staging	kaiko_test_xxx	https://stg.api.kaikostudios.xyz

Using a Key

Add your API key using one of these methods:

Header (Recommended):

x-api-key: kaiko_live_xxxxxxxxxxxxx

Bearer Token (Alternative):

Authorization: Bearer kaiko_live_xxxxxxxxxxxxx

Example V2 request with curl:

cURL Examplebash

curl -X POST https://api.kaikostudios.xyz/v2/emotions/analysis \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "emotion-v2",
    "messages": [{"role": "user", "content": {"text": "hello"}}]
  }'

2. Key Management

Rotate regularlygenerate new keys periodically, update your apps, and revoke old ones.
Least privilegeuse separate keys for dev, staging, and production environments.
Revoke if compromisedimmediately delete a key if it may have leaked.
Audit logscheck the console for when and where keys were used.

3. Idempotency

For POST requests that might be retried (e.g., after a timeout), supply an Idempotency-Key header:

Idempotency Headerbash

Idempotency-Key: 7f65ab21d1-test-123

Ensures the request is processed only once.
Useful for preventing duplicate chat completions or emotion analyses.
Keys should be unique per operation (UUIDs recommended).

4. Data Handling & Retention

Context-Based Emotion API (V2):

Emotional states tied to a context_id are stored temporarily for session continuity. V2 also stores trajectory and growth data.

Default retention: 24 hours (configurable).
After expiry, states are deleted and cannot be retrieved.

Stateless Analysis API:

No state is stored; analysis is ephemeral.

Chat API:

Messages may be stored transiently for processing but are not persisted beyond request lifetime.

5. Security Practices

TLS Everywhereall endpoints require HTTPS (https://).
No client-side keysnever embed API keys directly in client apps (web or mobile). Use a secure backend proxy.
Environment variablesstore API keys in env vars or a secure secrets manager.
Monitoringtrack request volume and unusual patterns to detect abuse.

6. Compliance & Privacy

Kaiko APIs are designed for enterprise use and comply with industry-standard data handling practices.

PII: Kaiko does not require personal identifiers in text input. Developers are responsible for avoiding unnecessary PII.

Export controls: Certain features may be subject to regulatory restrictions.

7. Example Secure Workflow

Secure Integration Patternplaintext

1. Store Kaiko API keys in a secrets manager (AWS Secrets Manager, GCP Secret Manager, Vault).
2. Application backend fetches keys securely at runtime.
3. Clients (mobile/web) never see raw Kaiko keys — they call your backend.
4. Backend adds x-api-key when forwarding requests to Kaiko.
5. Use Idempotency-Key for retries and log all request_id values.

Next: see Rate Limits & Error Handling to learn how to handle errors gracefully, or V2 EQ Dimensions to explore the new emotional intelligence features.