Skip to main content

Mint a visitor session

The widget runs in your visitor's browser and can't hold a long-lived secret. Instead, your backend mints a short-lived visitor JWT for each session and hands it to the widget. This guide shows the backend half.

Prerequisites​

  • A widget provisioned in your tenant portal (you have its WIDGET_ID).
  • An OAuth2 client with the widget_sessions:write scope (see API credentials).

1. Mint a client-credentials token​

TOKEN=$(curl -s -X POST https://$WISELOOK_HOST/auth/application/o/token/ \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode 'scope=widget_sessions:write' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["access_token"])')

2. Mint the visitor session​

curl -s -X POST "https://$WISELOOK_HOST/v1/widgets/$WIDGET_ID/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"external_user_id": "user-42"}'

external_user_id is your stable identifier for the visitor. Wiselook uses it to find-or-create the tenant end-user, so repeat sessions for the same visitor map to the same record.

The response contains the visitor JWT (plus the widget's methodology and locale). Hand the JWT to the widget.

3. Hand the token to the widget​

// Your page fetches the visitor JWT from your own backend endpoint,
// which wraps the call above — never expose the client secret to the
// browser.
const { token } = await fetch('/my-backend/wiselook-session').then(r => r.json());

window.Wiselook.mount('#assessment', {
  widgetId: 'WIDGET_ID',
  token,
});

Notes​

  • The visitor JWT expires in ~15 minutes and is bound to the widget's allowed origins — a leaked token can't be replayed from another site.
  • Mint a fresh token per session; don't cache them across visitors.
  • The /v1/widgets/{id}/sessions endpoint is the one public endpoint that takes a client-credentials token rather than a visitor JWT — it's how the visitor JWT itself is born.