API keys

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:

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:

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

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 server-side instead. Treat any leaked key as compromised and revoke it.

Session tokens

The browser-safe, short-lived credential for end users.

Usage & budgets

Org caps, per-key sub-limits, and budget webhooks.

Get started

Concepts

Agent project

The CLI

Deploy

Platform

Security

Enterprise

Tutorials

Shape and storage

Scopes

Create and manage

Keep keys safe

Session tokens

Usage & budgets

​Shape and storage

​Scopes

​Create and manage

​Keep keys safe

Session tokens

Usage & budgets

Shape and storage

Scopes

Create and manage

Keep keys safe