> ## 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.

# Authentication

> Two credential types - API keys and session tokens - and where each one is valid.

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:

```bash theme={null}
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](/platform/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:

```bash theme={null}
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](/api-reference/adapters/overview) - 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](/api-reference/errors)).

See [Session tokens](/security/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.

<Warning>
  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](/security/session-tokens) server-side for the edge instead.
</Warning>

## 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](/api-reference/errors) for the full table.