Authentication

Karta recognizes two credential types. Each one resolves to an org, a set of scopes, and the current 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 by Karta; org-scoped.
Carries explicit fine-grained scopes such as releases:write or webhooks:write.
Every authenticated request is checked against the org’s current budget state.
Valid on both the flat /v1/sessions/... family and the agent /{org}/{agent}/v1/... family.

See API keys for shape, scopes, and storage.

Session token

A short-lived, agent-scoped signed token your backend mints for an end user’s browser. Present it the same way:

curl https://agent.karta.sh/my-org/my-app/v1/managed-agents/sessions \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" -d '{}'

Pins org_id, agent_id, agent_slug, scope, exp.
Valid only on the agent’s consumer adapters - the Managed Agents API and the OpenAI-compatible routes. The native /{org}/{agent}/v1/sessions routes and the flat routes require an API key.
Verified by Karta without a network round-trip.
Minting requires the org to be within budget: an over-budget org gets 402 from the mint endpoint (see Errors).

See Session tokens for the mint-and-use flow.

Choosing the right credential

Caller	Credential	Routes
Your backend	`kt_live_...` API key	flat + agent native + adapters
An end user’s browser/widget	session token	consumer adapters only

Route family matrix

Route family	Example	`kt_live_...` API key	Session token
Flat native API	`https://api.karta.sh/v1/sessions`	Yes	No
Agent native API	`https://agent.karta.sh/{org}/{agent}/v1/sessions`	Yes	No
Managed Agents adapter	`https://agent.karta.sh/{org}/{agent}/v1/managed-agents/...`	Yes	Yes
OpenAI adapters	`https://agent.karta.sh/{org}/{agent}/v1/chat/completions`	Yes	Yes
Management API	`https://karta.sh/api/agents/{slug}/session_tokens`	Yes, with the required scope	No

Use an API key on servers and management routes. Use a session token only where an end-user browser needs to drive a specific deployed agent.

Never ship a kt_live_... key to a browser or mobile client. It is a server credential that may carry broad org authority. Mint a session token server-side for the edge instead.

Auth failures

Status	Meaning
`401`	Missing or invalid credential.
`403`	Authenticated, but refused - a metadata end-user id that conflicts with the verified token (`identity_mismatch`), or an API key lacking the required scope.
`404`	Resource not found, belongs to another org, or a session token scoped to another agent. All are shaped identically (default-deny), so the URL space is never a tenant oracle.
`402`	Authenticated, but the org’s budget is exhausted.

See Errors for the full table.

Overview

Sessions

Consumer adapters

Authentication

API key (`kt_live_...`)

Session token

Choosing the right credential

Route family matrix

Auth failures

​API key (kt_live_...)

​Session token

​Choosing the right credential

​Route family matrix

​Auth failures

API key (`kt_live_...`)

Session token

Choosing the right credential

Route family matrix

Auth failures