Authentication

Kapable supports two authentication methods: API keys for server-to-server calls and JWT bearer tokens for user-context requests.

API Key Authentication

API keys are the simplest way to authenticate. Pass the key in the x-api-key header on every request.

# API key auth
curl https://api.kapable.ai/v1/board/stories \
  -H "x-api-key: sk_live_abc123..."

Getting an API Key

1. Log in to the Kapable Console
2. Navigate to Settings → API Keys
3. Click Create Key and copy the displayed value

SDK Usage

const client = new KapableClient({
  baseUrl: 'https://api.kapable.ai',
  apiKey: process.env.KAPABLE_API_KEY,
});

// Rust SDK
let client = KapableClient::new("https://api.kapable.ai")
    .api_key(std::env::var("KAPABLE_API_KEY").unwrap())
    .build();

JWT Bearer Token

For user-context requests (e.g. from a frontend), use a JWT token obtained via the Auth service's login endpoint. Pass it in the Authorization header.

# Bearer token auth
curl https://api.kapable.ai/v1/board/stories \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Obtaining a Token

// Login and get a token
const { token } = await client.auth.login({
  email: 'user@example.com',
  password: '...',
});

// Use the token for subsequent requests
const authedClient = new KapableClient({
  baseUrl: 'https://api.kapable.ai',
  token,
});

// Rust SDK
use kapable_sdk::auth::types::LoginRequest;

let resp = client.auth().login(&LoginRequest {
    email: "user@example.com".into(),
    password: "...".into(),
}).await?;

let authed_client = KapableClient::new("https://api.kapable.ai")
    .token(resp.token)
    .build();

Org Context

All API calls are scoped to the authenticated org. API keys are org-bound. JWT tokens carry the org ID in the token claims. Multi-org users select their active org during login.

Agent Keys (Comms)

The Comms service supports a third auth model: agent keys. These are per-agent API keys minted via POST /v1/agents/{id}/keys that allow agent processes to authenticate directly for SSE streaming and message sending.

// Mint an agent key
const { key } = await client.comms.mintAgentKey(agentId, {
  label: 'production',
});

// Use it to connect the agent's SSE stream
const stream = new EventSource(
  `https://api.kapable.ai/v1/agents/${agentId}/stream`,
  { headers: { 'x-api-key': key } }
);

// Rust SDK
use kapable_sdk::comms::types::MintAgentKeyRequest;

let resp = client.comms().mint_agent_key(agent_id, MintAgentKeyRequest {
    label: "production".into(),
}).await?;
println!("Agent key: {}", resp.key);

App Tokens (Comms)

For service-to-service integration with the Comms internal endpoints, use app tokens. These are org-scoped tokens for programmatic access to intercept and send operations.

// Mint an app token for your integration
const { token } = await client.comms.mintAppToken(orgId, {
  label: 'email-worker',
});

// Rust SDK
use kapable_sdk::comms::types::MintAppTokenRequest;

let resp = client.comms().mint_app_token(org_id, MintAppTokenRequest {
    label: "email-worker".into(),
}).await?;

Error Responses

Authentication failures return a 401 Unauthorized response:

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