Skip to main content
Kalinklo · Artists
Developer portal

Developer docs

Auth and Rate Limits

Bearer-token scheme, key lifecycle, rate-limit headers, and retry policy.

Authentication

All non-public endpoints require a bearer token in the Authorization header:

Authorization: Bearer kal_live_xxxxxxxx
Accept: application/json

Tokens follow the shape kal_<env>_<random> where <env> is live or test. Live keys act on production data; test keys act on the test workspace tied to your account.

Missing or malformed Authorization returns 401. A syntactically valid token that is revoked or expired returns 401 with error.code = "INVALID_TOKEN". A token that authenticates but lacks entitlement to the requested action returns 403 with error.code = "FORBIDDEN".

Key lifecycle

Keys are administered from your workspace settings (the developer console is in build-out during the charter; for now, key issuance is manual — apply at /pilot).

You can:

  • Rotate a key — issues a new one, invalidates the old after a configurable grace window (default 24h)
  • Revoke a key — immediate invalidation, no grace window
  • Scope a key — restrict to a list of endpoints / actions

Rate limits

Rate limits are enforced per token per route group. Public endpoints are limited per IP. Limits live in the route-guards module and are conservative by default.

Every response carries:

  • X-RateLimit-Limit — total requests permitted in the window
  • X-RateLimit-Remaining — requests left in the current window
  • X-RateLimit-Reset — Unix timestamp at which the window resets

A 429 Too Many Requests response also includes Retry-After (seconds). Clients should respect both Retry-After and the X-RateLimit-Reset value, whichever is later.

Retry policy

For transient errors (429, 502, 503, 504):

  1. Wait at least Retry-After seconds (default to 1 second if absent).
  2. Apply exponential backoff capped at 30 seconds.
  3. Add jitter of ±20% to avoid thundering-herd retries.
  4. Stop after 5 attempts; surface the error to the operator.

Do not retry 4xx errors except 429. They will not succeed without changing the request.

Security

  • Never embed live keys in browser bundles or mobile apps. Use a server-side proxy.
  • Keep keys in environment variables, not source control.
  • Use distinct keys per environment (test vs live).
  • Rotate keys on suspected exposure; the grace window is intentional but limited.

Where to next

Request accessSign in