`.
5. The widget talks to Hatched directly, signed with the session token.
```ts
const session = await hatched.widgetSessions.create({
buddyId: 'bdy_abc',
userId: 'user_42',
scopes: ['read', 'events:track', 'marketplace:browse', 'marketplace:purchase', 'items:equip'],
ttlSeconds: 60 * 15,
});
```
**Rules.**
- Short-lived (minutes, not hours). Re-mint on focus or route change.
- Scoped to one `buddyId`. If you switch buddies, re-mint.
- Scoped to the exact list of widget scopes you pass. A session minted
without `marketplace:purchase` cannot buy items even if the widget tries.
## Embed token
Read-only sibling of widget session tokens. Stateless and cheap to mint —
pass one per buddy/widget render on a page.
**This is the token that confuses people most often.** It is *not* something
you create once in the dashboard like an API key. It is a short-lived JWT
that your backend mints on demand — typically inside a route handler — and
hands to the browser for the page render.
### Why it exists
The widget runs in the user's browser. It needs *some* token to identify
which buddy to display, but you cannot put a secret API key in the browser
(any visitor could read it from devtools and call mutating endpoints with
your account's full authority). The embed token solves this: it is signed
by Hatched, scoped to one `(userId, buddyId)` pair, expires automatically,
and can only do read-only widget display: buddy, badges, streaks,
leaderboards, and marketplace catalog/state.
### How to mint one
```ts
// app/api/hatched/embed-token/route.ts — Next.js
import { HatchedClient } from '@hatched/sdk-js';
const hatched = new HatchedClient({ apiKey: process.env.HATCHED_API_KEY! });
export async function POST(req: Request) {
const { userId, buddyId } = await req.json();
const embed = await hatched.embedTokens.create({
userId,
buddyId,
ttlSeconds: 60 * 60, // 1h is a reasonable default
});
return Response.json({ token: embed.token, expiresAt: embed.expiresAt });
}
```
Or with raw HTTP if you do not use the SDK:
```http
POST /embed-tokens
Authorization: Bearer hatch_live_xxxxxxxxxxxx
Content-Type: application/json
{ "user_id": "user_42", "buddy_id": "bdy_abc", "ttl_seconds": 3600 }
```
Response:
```json
{ "token": "eyJhbGciOi…", "expires_at": "2026-05-05T16:00:00Z", "mode": "read-only" }
```
### How it reaches the browser
```html
```
### Lifecycle
- **Stateless**: Hatched does not store embed tokens. Validity comes from
the JWT signature and the `exp` claim — there is no revocation list.
- **TTL**: minimum 5 minutes, maximum 24 hours, default 24 hours. Pick the
shortest TTL that fits your render cadence.
- **Re-mint, do not cache for long**: mint on each page request (or each
SPA route change). The mint call is cheap.
- **Difference from a widget session token**: an embed token can only
*display* — it cannot send events, equip items, or buy from the
marketplace. For interactivity, use a widget session token instead.
## What lives where
| Layer | Token |
| ---------------------------------------------------------- | ----------------------------------- |
| `.env` / Vercel secrets / GitHub secrets | Secret API key |
| `NEXT_PUBLIC_HATCHED_PK` / HTML `
` | Publishable key |
| Request to your `/api/hatched/session` endpoint | — returns widget session token |
| `data-session-token` / `data-embed-token` script attribute | Widget session token or embed token |
## What not to do
- ❌ Put a secret key in a `.env.production` file that gets shipped to the
browser via Vite/webpack `DefinePlugin`. Check your bundler output.
- ❌ Use a session token to call the raw API from `fetch` — session tokens
are only accepted by the widget runtime.
- ❌ Reuse a single session token across many users — tokens are
user-bound.
- ❌ Assume a publishable key is "read-only enough" to skip scope review —
check the scope set before publishing a new one.
## Related
- [Widget integration](/docs/guides/widget-integration)
- [Browser usage with publishable key](/docs/guides/browser-usage)
- [Error: publishable_key_scope](/docs/reference/error-codes#publishable-key-scope)