Skip to main content
A session token is how an end user’s browser reaches a Karta agent safely. A kt_live_... key is an org-wide management credential and must never ship to a client. Instead, your backend mints a short-lived, agent-scoped signed token per authenticated end user, and the widget presents that. This is the standard “ephemeral client secret” pattern: the long-lived secret stays on your server; a narrow, expiring token reaches the browser.

​
The flow

1

Your backend mints a token

After your own auth confirms the user, call the mint endpoint with your kt_live_... key that has the agents:write scope. You get back a signed token scoped to one org + agent, with an expires_in value. If the org or verified end user is over budget, the mint endpoint returns 402 instead of a token.
2

The widget uses it

The browser presents the session token to the agent’s consumer adapter routes - the Managed Agents API the chat widget speaks, and the OpenAI-compatible Responses and Chat Completions adapters. It does not work on the native session routes (/v1/sessions, /{org}/{agent}/v1/sessions) - those are your backend’s surface and require a kt_live_ API key.
3

Karta verifies it offline

Karta verifies the token’s signature, scope, and expiry - without a network round-trip.

​
Mint response

​
TTL bounds

If you pass ttl_seconds, Karta clamps it into that range.

​
What the token pins

The minted token pins org_id, agent_id, agent_slug, scope, and exp. Because org and agent are pinned, cross-tenant access is blocked: a token for one agent cannot touch another. When the widget mints from an embed key with verified identity, the token also carries sub, the server-verified subject for your signed-in user. If your server provides a signed step-up identity token, the session token can also carry recent stepped_up_at / aal claims for sensitive approvals.
Keep the TTL short. A session token is scoped to one org + agent and expires after a 900-second default. Without verified identity it is not bound to an individual end user; with verified identity it is bound to the signed sub. Mint a fresh token per user session so a leak is contained to that token’s lifetime.

​
Use session tokens in browsers

A kt_live_... key is a server credential. Depending on scopes, it can manage keys, BYOK, budgets, and deploys. Putting one in a browser or mobile app exposes server-side authority. The session token exists precisely so the browser never needs the key: it is minted server-side, scoped to a single agent, and expires in minutes.
See Trust for where this sits in the full trust model, and API keys for the credential it replaces at the edge.