Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.karta.sh/llms.txt

Use this file to discover all available pages before exploring further.

The data plane recognizes three credential types, each resolving to a Principal that carries the org id, scopes, and budget status.

​
API key (kt_live_…)

Your server’s bearer token. Present it on every request: 
curl https://api.karta.sh/v1/sessions \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"customer_id": "abc123"}}'
  • Validated against the control plane (cached ~5s); org-scoped.
  • Carries scopes (read, write, admin) and a budget_ok flag.
  • Valid on both the flat /v1/sessions/… family and the project /v1/projects/{ref}/… family.
See API keys for shape, scopes, and storage.

​
Session token (JWT)

A short-lived, project-scoped HS256 JWT your backend mints for an end user’s browser. Present it the same way: 
curl https://api.karta.sh/v1/projects/my-app/sessions \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" -d '{}'
  • Pins org_id, project_id, project_slug, scope, exp.
  • Valid only on the project /v1/projects/{ref}/… family and the consumer adapters — not the flat routes.
  • Verified offline by the data plane (no control-plane round trip).
See Session tokens for the mint-and-use flow.

​
Service token (internal only)

A shared bearer used by the control plane for /v1/internal/* endpoints, defended by IP and Host allowlists. Not part of the public API; never held by a customer.

​
Choosing the right credential

CallerCredentialRoutes
Your backendkt_live_… API keyflat + project
An end user’s browser/widgetsession tokenproject + adapters
The control planeservice tokeninternal only
Never ship a kt_live_… key to a browser or mobile client — it’s an org-wide management credential. Mint a session token server-side for the edge instead.

​
Auth failures

StatusMeaning
401Missing or invalid credential.
403Valid token, wrong project (a session token scoped elsewhere).
404Resource not found or belongs to another org (default-deny).
402Authenticated, but the org’s budget is exhausted.
See Errors for the full table.