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.

Karta authenticates server-to-platform traffic with API keys: bearer tokens shaped kt_live_<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_ followed by 32 characters.
  • Only a bcrypt digest is stored, plus a 14-character prefix for indexed lookup. The plaintext is revealed exactly once at creation (held briefly in a server-side cache) and never again.
  • Validation is two-step on purpose: find by prefix, then run a constant-time bcrypt comparison, then check revocation. bcrypt always runs before the revocation check, so a prefix-only probe can’t leak revocation state through timing.

​
Scopes

Keys carry scopes that gate what they can do:
ScopeGrants
readList keys, usage, projects, releases, logs.
writeDeploy a release; mint session tokens.
adminCreate/revoke keys; roll back releases.
Scope your keys to the least privilege a caller needs — a CI deploy key wants write, not admin.

​
Create and manage

From the dashboard, or the TypeScript management SDK: 
import { Karta } from "@karta/sdk";
const karta = new Karta({ apiKey: process.env.KARTA_API_KEY! });

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

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

​
How validation works on the hot path

On each customer request the data plane validates the key against the control plane, getting back a Principal (org id, scopes, budget_ok). The result is cached for a short TTL (default 5s) to amortize the bcrypt cost, and the control plane push-invalidates that cache on revocation, plan, or budget changes. So a revoked key stops working within the staleness window without a bcrypt call on every request. See Architecture → how the planes talk.

​
Keep keys safe

A kt_live_… key is an org-wide management credential. Never ship it to a browser or mobile client. For frontend/end-user access, mint a short-lived, project-scoped session token server-side instead. Karta scrubs kt_live_* (and sk-ant-*, whsec_*, bare Bearer …) from logs and error reports, but treat any leaked key as compromised and revoke it.

Session tokens

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

Usage & budgets

Per-key sub-limits and org caps.