Skip to main content

Authentication

The Agent SDK authenticates with the Kapa API using short-lived session tokens. Your server creates these tokens using your API key, and the SDK uses them to stream responses.

How it works​

  1. The browser calls your server endpoint (e.g. POST /api/session)
  2. Your server calls the Kapa session API with the X-API-Key header
  3. Kapa returns a session token (valid for 1 hour)
  4. Your server forwards the token to the browser
  5. The SDK uses the token for all subsequent API calls

The API key never leaves your server.

Session endpoint​

POST https://api.kapa.ai/agent/v1/projects/{projectId}/agent/sessions/

Headers:

  • X-API-Key: your-api-key

Response:

{
  "session_token": "NRd60UqDpLSeeIFzCfmj5dxiRDOJL8G7aSXVzpQ0pPusbe9kHIjEymznutrJu6uf",
  "expires_at": "2026-03-17T09:54:51.165812Z"
}

Server-side proxy example​

Your getSessionToken function should call your own server, which proxies the request:

getSessionToken={async () => {
  const res = await fetch('/api/session', { method: 'POST' });
  if (!res.ok) throw new Error('Session creation failed');
  return res.json();
}}

Your server just passes through the Kapa API response:

const response = await fetch(
  `https://api.kapa.ai/agent/v1/projects/${projectId}/agent/sessions/`,
  { method: 'POST', headers: { 'X-API-Key': apiKey } },
);
res.json(await response.json());

The SDK accepts the raw Kapa API response ({ session_token, expires_at }) directly — no transformation needed. It also accepts the normalized format ({ token, expiresAt }).

Token lifecycle​

The SDK manages tokens automatically:

  • Lazy fetching — getSessionToken is not called until the user sends their first message
  • Caching — tokens are cached and reused for subsequent requests
  • Auto-refresh — tokens are refreshed 30 seconds before expiry
  • Retry on 401 — if a request fails with 401, the token is cleared and a fresh one is fetched
  • Deduplication — concurrent refresh calls are deduplicated (only one getSessionToken call at a time)

Getting your credentials​

API key​

  1. Log in to your Kapa dashboard
  2. Navigate to Settings → API Keys
  3. Create or copy an existing API key
  4. Store it as a server-side environment variable (e.g. KAPA_API_KEY)

Project ID and Integration ID​

  1. In your Kapa dashboard, go to Integrations → Agent
  2. Create an Agent integration if you don't have one
  3. Copy the Project ID and Integration ID from the integration setup page
  4. The Project ID is used both in the session endpoint URL and as the projectId prop on AgentProvider
  5. The Integration ID is passed as the integrationId prop on AgentProvider