Karta has three human personas and one non-human actor. The authentication and authorization boundaries fall on the sub-roles, not the persona labels — so this page names the actors, their tools, the credentials they hold, and the trust lines between them.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.
The actors at a glance
| Persona | Who | Lives in | |
|---|---|---|---|
| A | Platform operator | Karta itself | A separate, more-privileged admin plane |
| B | Harness-app builder | Your org and its members | The dashboard, the karta CLI, and your own backend |
| C | End user | A consumer of B’s deployed app | A chat widget on B’s site — never on Karta |
| D | The agent | The deployed harness at runtime | The sandbox, with its own runtime principal |
A: the platform operator
Two hats with very different blast radius:- Product engineer — builds the planes, adapters, CLI, and SDKs. Holds development secrets only; never a production service token.
- Platform operator / SRE — provisions the substrate, runs the build
pipeline, rotates
KARTA_SERVICE_TOKENS, monitors abuse, responds to incidents. Holds the most powerful credentials in the system.
The trust claim
B: the harness-app builder
“The builder” is really an Organization and its members, with five roles:owner, admin, developer, billing, viewer. Deploy, billing, and
read-only are distinct authz surfaces inside B.
| Task | Tool | Auth used |
|---|---|---|
Author the app (.claude/ + CLAUDE.md, skills, agents) | local repo, karta dev/run | none (local) |
| Register the project | dashboard / karta project add | Devise login |
| Deploy | git push karta, @karta/cli deploy, or POST /deploys | kt_live_… (write) |
| Roll back | dashboard / @karta/cli rollback | kt_live_… (admin) |
| Manage keys, BYOK, budgets, webhooks | dashboard | Devise; admin/owner |
| Mint session tokens for C (server-side) | POST /agent_projects/:slug/session_tokens | kt_live_… |
| Debug live sessions | karta session list/logs/interact | kt_live_… / Devise |
| Embed the widget | B’s frontend | relays the session-token JWT |
C: the end user
The cleanest boundary in the system: C has no Karta identity at all.- C authenticates on B’s site with B’s own auth — not Karta.
- The only credential that reaches C’s browser is a short-lived, project-scoped session token, minted server-side by B.
- C’s identity is opaque. Karta keys the workspace on
(tenant_id, user_id)from metadata B supplies and does not introspect it.user_idis a B-defined arbitrary string; Karta treats it as opaque bytes — normalized for filesystem safety, never parsed. Format and granularity are B’s contract.
Agents as principals
When a deployed harness app runs, the agent is itself an actor — not a passive extension of C. It has shell and tool access and can be steered by C’s input or by data it fetches (prompt injection). The data plane issues it a distinct runtime principal, and its authority must be explicitly bounded and scoped to the current C, never inherited ambiently.The credential matrix
| Credential | Held by | Authenticates | Scope |
|---|---|---|---|
| Devise login (+ TOTP / passkey) | B’s humans | a person → dashboard | one org membership + role |
kt_live_… API key | B’s backend | server → control/data plane | one org |
| Session token (JWT) | C’s widget (minted by B) | a browser → consumer session API | one org + project, ~15 min TTL |
KARTA_SERVICE_TOKENS | A only | Rails ↔ Python | the whole internal surface |
| BYOK provider key | B (stored by A, encrypted) | the harness → model provider | one (org, provider) |
kt_live_… key. The session token is the
only credential that reaches the browser — minted server-side, short-lived, and
project-scoped.
Session tokens
The mechanics of the browser-safe credential.
Trust & compliance
Encryption, auth hardening, and sub-processors.