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.

1. API Keys

Obtaining a Key

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

Using a Key

Add your API key to the x-api-key header for every request:

Header Formatbash
x-api-key: YOUR_API_KEY

Example with curl:

cURL Examplebash
curl https://api.kaiko.ai/v1/emotions/analyse \
  -H "x-api-key: $KAIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"emotion-v1","messages":[{"content":{"text":"hello"}}]}'
2. Key Management
  • Rotate regularly →generate new keys periodically, update your apps, and revoke old ones.
  • Least privilege →use separate keys for dev, staging, and production environments.
  • Revoke if compromised →immediately delete a key if it may have leaked.
  • Audit logs →check 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:

Emotional states tied to a context_id are stored temporarily for session continuity.

  • Default retention: 24 hours (configurable — document your actual TTL).
  • After expiry, states are deleted and cannot be retrieved.

Non-Context API:

No state is stored; analysis is ephemeral.

Chat API:

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

Opt-out flags:

Future releases will support client-side flags to disable temporary logging.

5. Security Practices
  • TLS Everywhere →all endpoints require HTTPS (https://).
  • No client-side keys →never embed API keys directly in client apps (web or mobile). Use a secure backend proxy.
  • Environment variables →store API keys in env vars or a secure secrets manager.
  • Monitoring →track 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 Models to explore available models.