Scenaro uses a two-step authentication flow. Identity (JWT) is separate from the Transport session credentials.
If you use useScenaroSession (React) or ScenaroSession (headless), both steps run automatically when you call start(). This page documents the underlying client flow.

Flow diagram

Step 1 — Identify

Request body (POST /v1/public/token):

Client-side caching

identifyUser is idempotent: if a non-expired user_token with user_id and application_id exists in storage, it returns the cached identity without a network call.

external_id

If you omit externalId, the SDK generates a stable anonymous ID and persists it. This consolidates conversations for returning visitors without login.

Step 2 — Start session

language is optional — omit it and the backend applies the scenario’s configured language. Request body (POST /v1/public/session):
Requires Authorization: Bearer {user_token}.

Token refresh outside sessions

Features that call the API outside the Transport session (search, cart) use:
This returns the stored token if valid, otherwise silently re-identifies using persisted scenario_uuid and external_id.

JWT expiration

Tokens are validated locally with a 90-second buffer (EXPIRY_BUFFER_SECONDS). No server round-trip is needed to check expiration.

Deprecated flow

The legacy generateToken single-call flow (one request creating user + session) has been removed. Do not implement it in new integrations.

Clear session

Removes the app-scoped identity blob and scenario pointer. See Session storage for key details.

API reference

See the API Reference tab for full request/response schemas.