Skip to main content
Puntego uses three credential classes, each scoped to exactly what it needs. The embedded guide on your site runs on a short-lived visitor JWT, your dashboard and tenant APIs run on a signed-in session, and server-to-server integrations use a scoped API key. Nothing in the browser ever holds a credential that can change workspace configuration or read another workspace.

The visitor JWT

The guide never ships with a long-lived secret. When the boot script loads, the browser calls POST /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.
Once the browser has a token, every guide request that needs identity sends it as a bearer token:
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 prefixed pk_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:
scope
Read aggregate conversation rows from /api/export/conversations. This scope does not grant transcript text.
scope
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.
scope
Read runtime event rows from /api/export/events.
scope
Read deterministic 20% sampled, pattern-scrubbed transcript turns from /api/export/transcripts. This materially more sensitive scope is independent of aggregate analytics.
scope
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.
scope
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.
scope
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.
The two authoring scopes are deliberately separate rungs and neither implies the other; 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_...>):
A missing or invalid export key returns 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.
Treat keys as least-privilege by default: grant only the scope a job needs, use a distinct key per integration, and revoke from the dashboard to rotate. Because keys are hashed at rest, rotation is the recovery path if one is ever exposed.

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.