Authentication & tokens

The SDK gets a participant identity from a bootstrap token your backend mints. It is the only way to inject real tokens — there is no static token prop.

The token flow

1. Your backend holds the secret
   Your server keeps the Dialogue secret key (sk_…). It never reaches the browser.
2. The SDK asks your endpoint for a token
   When it needs to authenticate, the SDK calls the bootstrapTokenProvider function you supplied. That function calls your endpoint.
3. Your endpoint exchanges secret → bootstrap token
   Your server calls Dialogue with the secret and returns the resulting bootstrap token to the browser.
4. The core exchanges it for a session
   The core hands the bootstrap token to Dialogue, receives a short-lived session token, and uses it for every participant call.

bootstrapTokenProvider

Supply an async function. The SDK calls it whenever it needs a fresh bootstrap token, so put your fetch to your own backend inside it.

<DialogueProvider
  publishableKey="pk_live_…"
  bootstrapTokenProvider={async () => {
    const res = await fetch('/api/dialogue-token', { method: 'POST' });
    if (!res.ok) throw new Error('token mint failed');
    return res.json(); // { bootstrapToken, expiresAt }
  }}
>
  {/* … */}
</DialogueProvider>

What you return

Resolve to a BootstrapTokenResult:

Degraded anonymous mode

If you omit bootstrapTokenProvider entirely, the SDK runs in degraded anonymous mode: it creates an anonymous participant session directly (the same POST /sessions the REST API exposes). The interview works end-to-end, but the participant has no carried identity across studies. This is the mode the demo runs in and is handy for local development.

Where tokens live

Tokens are held in main-thread closure memory only, never in cookies, localStorage, or IndexedDB. They vanish on reload. Because the SDK shares the host page’s context, the host page is the trust boundary; keep token minting server-side.