The visitor JWT
The guide never ships with a long-lived secret. When the boot script loads, the browser callsPOST /boot with your app ID (the gp_ token) from a page on a verified domain. The worker checks the origin against your allowlisted domains and, only then, mints a visitor JWT and returns it in the boot response.
The token is an HS256-signed JWT carrying the visitor ID, the workspace it was minted for, and the exact origin it was issued to. It has roughly a 15-minute TTL, so even if a token were captured it expires on its own and is bound to a single origin. The runtime refreshes it transparently by re-booting before it lapses — you never manage this yourself.
Ordinary
POST /boot authenticates by app ID plus verified origin and does not use 401: an unknown app, unrecognized origin, bot, or invalid visitor ID is a 403. A valid app and origin receive a restricted 200 privacy-controls-only session when normal assistant traffic is unavailable or the global killswitch is active; it preserves inspect/Forget access, but that JWT cannot authorize chat or the normal runtime. On a workspace eligible for full assistant boot, an explicitly supplied invalid, expired, or replayed customer_identity_token returns 401 and fails closed. Puntego never silently replaces a failed authenticated handoff with an anonymous assistant session. See the full mapping in Error reference.POST /chat validates the signature and expiry on every turn. A missing or invalid token is chat/unauthorized (401), and an expired token returns jwt_expired (401) — the runtime treats that as its cue to re-boot. On top of authentication, /chat enforces per-visitor and per-workspace rate limits; see Rate limits.
The boot-then-chat handshake
The worker base URL is
https://worker.puntego.com. The boot script must pass data-gp-api pointing at it — without that attribute the worker is unreachable and no token is ever minted. See the install reference.Dashboard and tenant APIs
Your dashboard, and the tenant APIs it calls under/api/tenants/:tenantId/*, authenticate with a Better Auth session cookie established when you sign in at the Puntego dashboard. These APIs are organization-scoped: middleware ties the session to the member’s organization and blocks any attempt to read or write another workspace’s tenant ID. This is the only credential class that can change configuration — it lives in your dashboard session, never in the browser embed.
Programmatic API keys
For pulling your own data into a warehouse or minting a signed customer-identity handoff, create a scoped API key in your workspace dashboard. Keys are prefixedpk_live_, generated once, and stored only as a hash — the full secret is shown a single time at creation and never again.
API keys carry only the explicit scopes selected when they are created:
Read aggregate conversation rows from
/api/export/conversations. This scope does not grant transcript text.Start the guide in one of your visitors’ live sessions through the Assist API (
/api/v1/assist): your own AI agent asks, answers, shows the way or asks for an action the visitor approves on the page. Growth and higher. It cannot read exports or approve anything; keep it on your server.Read deterministic 20% sampled, pattern-scrubbed transcript turns from
/api/export/transcripts. This materially more sensitive scope is independent of aggregate analytics.Mint a short-lived, one-time customer identity token through
/api/identity/token. Available from Growth. Keep a key with this scope on your server; never expose it to the browser.Author Experiences, audiences, experiments, and Experience collections over
/api/v1/* from CI. Every write is optimistically concurrent, and this scope alone can never change what a live visitor sees — it cannot promote a revision, move lifecycle status, replace the items of an active collection, or change an active collection’s surface.Promote an already-authored revision to an environment and move lifecycle status over
/api/v1/*. It cannot author, so a deploy key leaked from a CI runner cannot introduce content nobody reviewed. Release-guardian warnings still cannot be waived by a key.GET reads accept either. Both are included from Growth, so infrastructure-as-code authoring is self-serve. See the API reference for the endpoint list and a copyable CI workflow.
analytics:read and transcripts:read also connect Claude, Cursor or any MCP client to the read-only workspace MCP server (/api/v1/mcp).
These scopes do not grant chat, workspace configuration, or Verified Action execution. Send the key in the x-api-key header (or as Authorization: Bearer <pk_live_...>):
export/unauthorized (401); a key without that endpoint’s exact scope returns export/insufficient_scope (403). Identity mint uses the matching identity/* errors. Programmatic endpoints are rate limited per key — see Rate limits.
Next steps
API reference
Every public worker endpoint — boot, chat, consent, export, and voice.
Error reference
The full status-code and error-namespace mapping, including anonymous and identity-bound boot behavior.
Rate limits
Per-visitor, per-workspace, and per-key limits, with the Retry-After contract.
Verified actions
How customer-approved tools layer policy checks on top of the visitor session.