API

How Authentication Works on the Kairos API

KairosAugust 21, 20264 min read

Quick answer

Kairos APIs accept two credential types: API keys, sent as X-Client-Id, X-Api-Key, and X-Api-Secret headers and created in the Kairos dashboard, and JWT bearer tokens for user-facing sessions. Read-only market data on the Market Data API's free tier needs neither.

API key authentication

HeaderDescription
X-Client-IdYour client ID, formatted like kairos_ck_...
X-Api-KeyYour API key
X-Api-SecretYour client secret
curl "https://data.kairos.trade/candles?provider=kalshi&contract_id=...&timeframe_seconds=3600" -H "X-Client-Id: kairos_ck_..." -H "X-Api-Key: ..." -H "X-Api-Secret: ..."

API key auth works on all read-only data endpoints (candles, trades, search, markets, discover, PnL providers) and on the Order Execution API, gated by scope. Market data, discover, search, and candle endpoints require no specific scope. Any active key grants access.

Scopes

ScopeAccess
trade:executeSubmit and cancel orders
trade:readView trade history and metrics (/trades/*)
position:readView PnL and portfolio data (/pnl/*)

No anonymous execution

Every execution.kairos.trade endpoint requires a credential or session JWT. There is no unauthenticated path, since this service moves money. The Data API's free reads do not extend here.

IP whitelisting and key security

  • Keys can be restricted to specific IP addresses. Requests from a non-whitelisted IP receive 403 Forbidden.
  • Keys and secrets are SHA-256 hashed before storage, never stored raw.
  • Credential comparisons run in constant time to resist timing attacks.

JWT bearer tokens

User-facing sessions authenticate with an HS256-signed JWT in the Authorization: Bearer header, or a ?token= query parameter for WebSocket compatibility. Tokens are issued by kairos.trade for the kairos-api audience and expire after 24 hours. A missing or invalid credential returns 401 with a detail message; the Order Execution API uses its own error envelope.

Protection levels

LevelRequirementExamples
PublicNo authGET /providers/configs, GET /sports/matching-markets
Data (read-only)JWT or API keyGET /candles, GET /trades/history, GET /search/markets
User authJWT with user identityGET /pnl/{user_id}

Frequently asked questions

Create it in the Kairos dashboard inside the app. The key comes as three credentials: a client ID, an API key, and a client secret, sent as the X-Client-Id, X-Api-Key, and X-Api-Secret headers on every request.
Yes. The Market Data API at md.kairos.trade has a free anonymous tier for candles, trades, and marks, with ETag caching. The full Data API and all execution endpoints require credentials.
The most common cause is IP whitelisting. Keys can be restricted to specific IPs, and a request from any other address receives 403 Forbidden even with valid credentials.

Related reading