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

# API keys

> Server-side kt_live_ bearer tokens, least-privilege scopes, expiration rules, and safe rotation.

Karta authenticates server-to-platform traffic with **API keys**: bearer tokens
shaped `kt_live_<32 chars>` or `kt_test_<32 chars>`. Your backend holds one and
presents it as `Authorization: Bearer kt_live_...`; your end users never do.

## Shape and storage

* The token is `kt_live_` or `kt_test_` followed by 32 characters.
* Karta stores a one-way digest plus a short prefix for display and lookup.
* The plaintext is revealed exactly once at creation. Store it immediately.
* Revoked and expired keys fail closed.
* Test-mode keys use the same API surface but do not bill live usage.

## Scopes

API keys carry only fine-grained operation scopes. Karta automatically translates
older coarse scopes to the equivalent operation scopes during deployment.

| Scope                                                                                          | Grants                                                                                                                      |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `agents:read`, `agents:write`, `agents:delete`                                                 | Inspect agents and invocations, change serving/model settings, or archive an agent.                                         |
| `analytics:read`, `billing:read`                                                               | Usage, analytics, and billing status reads.                                                                                 |
| `releases:read`, `releases:write`, `source_archives:read`                                      | List, activate, roll back, or download release archives.                                                                    |
| `caps:read`, `caps:write`                                                                      | Read or update org, karta, user, and seat spend caps.                                                                       |
| `webhooks:read`, `webhooks:write`                                                              | List or manage webhook endpoints.                                                                                           |
| `embed_keys:read`, `embed_keys:write`                                                          | List, create, rotate, disable, enable, or revoke widget embed keys.                                                         |
| `model_keys:read`, `model_keys:write`                                                          | List, create, or revoke BYOK model credentials.                                                                             |
| `members:read`, `members:invite`, `members:write`, `members:owner_role:write`                  | Read and manage organization membership.                                                                                    |
| `appearance:read`, `appearance:write`, `schedules:read`, `schedules:write`, `directories:read` | Manage agent appearance, schedules, and directories. Agent instructions update through deploys, not live API-key mutations. |
| `env:read`, `env:write`, `env:secrets:read`                                                    | Read, update, or export environment configuration and secrets.                                                              |
| `keys:read`, `keys:write`, `workspace_tokens:create`, `audit_log:export`                       | Inspect or manage API keys, mint workspace tokens, and export audit events.                                                 |
| `source_repos:read`, `source_repos:write`, `sessions:read`                                     | Pull or push hosted source repositories and inspect session metadata.                                                       |

Sensitive scopes require an expiration within 90 days:

`env:secrets:read`, `source_archives:read`, `workspace_tokens:create`,
`audit_log:export`, `members:invite`, `members:write`,
`members:owner_role:write`, `agents:delete`, `keys:write`, and
`model_keys:write`.

Scope your keys to the least privilege a caller needs. A CI release key usually
wants only `releases:write`.

## Create and manage

Use the CLI for day-to-day key management:

```bash theme={null}
karta keys list
karta keys create ci-release --scope releases:write
karta keys create audit-export --scope audit_log:export --expires-at <ISO timestamp within 90 days>
karta keys rename <key-id> "ci-release-prod"
karta keys revoke <key-id>
```

Or use the [TypeScript management SDK](/sdks/typescript/management):

```typescript theme={null}
import { Karta } from "@karta.sh/sdk";
const karta = new Karta({ apiKey: process.env.KARTA_API_KEY! });

const { api_key, secret } = await karta.apiKeys.create("ci-release", ["releases:write"]);
// `secret` (kt_live_...) is shown exactly once - store it now.

await karta.apiKeys.list();
await karta.apiKeys.revoke(api_key.id);
```

The dashboard, CLI, and API expose the same fine-grained scope set.

## Keep keys safe

<Warning>
  A `kt_live_...` key is an organization management credential. Never ship it to a
  browser or mobile client. For frontend/end-user access, mint a short-lived,
  agent-scoped [session token](/security/session-tokens) server-side instead.
  Treat any leaked key as compromised and revoke it.
</Warning>

<CardGroup cols={2}>
  <Card title="Session tokens" icon="ticket" href="/security/session-tokens">
    The browser-safe, short-lived credential for end users.
  </Card>

  <Card title="Usage & budgets" icon="gauge" href="/platform/usage-and-budgets">
    Org caps, per-key sub-limits, and budget webhooks.
  </Card>
</CardGroup>