Authentication

API Keys

All API requests must be authenticated using an API key. API keys are team-scoped, meaning each key is associated with a specific team and can only access that team's data.

Bearer Token Authentication

Include your API key in the Authorization header as a Bearer token:

curl -X GET "https://gateway.thekairos.app/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

When using an SDK, authentication is handled automatically:

import { Kairos } from '@kairos-connect/sdk';

const kairos = new Kairos({
  apiKey: process.env.KAIROS_API_KEY, // Always use environment variables
});

// The SDK handles authentication automatically
const tasks = await kairos.tasks.list();

Scopes

API keys use scopes to control access to different resources. When creating a key, select only the scopes your integration needs.

Rate Limiting

API requests are rate limited to prevent abuse. Limits are applied per API key.

Rate limit information is included in response headers:

Error Handling

Authentication errors return a 401 Unauthorized status:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key",
    "request_id": "req_abc123"
  }
}

Security Best Practices

• *Never expose API keys in client-side code. Always make API calls from your backend.
• *Use environment variables to store API keys rather than hardcoding them.
• *Rotate keys regularly and immediately revoke any keys that may have been compromised.
• *Use the minimum required scopes for each API key.
• *Set expiration dates on API keys when possible.

Next Steps