Skip to main content

Manage sessions and visitor identity

The public site key identifies an allowed Widget installation; it is not a credential. Visitor actions use a short-lived access grant issued by Qanivo for one browser session, Connection, audience, and allowed origin. Grants are sent in Authorization: Bearer ..., never in a URL, and are bounded by the server policy.

Session lifecycle​

The package creates a session during mount() and renews it before expiry. A host integration should keep the Widget instance mounted while the visitor remains on the site and subscribe to terminal events:

widget.on('session.expired', () => {
  showSignInOrRefreshMessage();
});

// Revoked and expired grants are exposed through the terminal session event.
widget.on('session.expired', () => {
  closeVisitorSurface();
});

The session response contains a session identifier, access grant, expiry, renewal timing, renewal token, replay state, and conversation continuity state. Do not persist these values outside the package storage mode. session storage is tab-scoped; memory keeps state only in memory. localStorage is not a supported continuity store.

The runtime retries transient network, 429, and 5xx renewal failures with bounded backoff while the current grant remains valid. Expired, revoked, disabled, or banned sessions are terminal and must not be hidden by a retry loop.

HTTP session create and renewal​

The browser sends Origin and X-Qanivo-Widget-Version: 1.0 on public requests. Side effects require a stable Idempotency-Key.

POST /api/integrations/v1/widget/sessions HTTP/1.1
Origin: https://www.example.invalid
X-Qanivo-Widget-Version: 1.0
Idempotency-Key: <YOUR_SESSION_OPERATION_ID>
Content-Type: application/json

{
  "publicSiteKey": "<YOUR_PUBLIC_SITE_KEY>",
  "clientInstanceId": "<YOUR_BROWSER_INSTANCE_ID>",
  "locale": "en-US",
  "pageContext": { "section": "pricing" }
}

Renewal uses the current session and renewal state. A recoverable failure must not revoke a still-valid session; a terminal response must be surfaced as terminal.

POST /api/integrations/v1/widget/sessions/renew HTTP/1.1
Origin: https://www.example.invalid
X-Qanivo-Widget-Version: 1.0
Authorization: Bearer <YOUR_ACCESS_GRANT>
Idempotency-Key: <YOUR_RENEWAL_OPERATION_ID>
Content-Type: application/json

{
  "sessionId": "<YOUR_SESSION_ID>",
  "renewalToken": "<YOUR_RENEWAL_TOKEN>",
  "lastSeenEventId": "<YOUR_LAST_EVENT_ID>"
}

Logged-in visitor identity​

Use identityProvider when the host has an authenticated visitor. The provider should call the host backend, which creates a short-lived signed identity assertion. The browser receives the assertion; it never receives the signing secret.

const widget = createQanivoWidget({
  siteKey: '<YOUR_PUBLIC_SITE_KEY>',
  apiBaseUrl: 'https://api.example.invalid',
  identityProvider: async () => {
    const response = await fetch('/api/me/widget-identity', {
      credentials: 'include',
      headers: { Accept: 'application/json' },
    });
    return response.ok ? response.json() : undefined;
  },
});

The backend validates the assertion type, external subject, issued/expiry times, nonce, signature, and replay state. Initial information such as a plan label or account reference is bounded context, not authorization. Never put a provider credential, signing secret, or unrestricted customer payload in the assertion or page context.

Identity operations and privacy boundaries​

The Widget API exposes identity operations through the instance:

await widget.identify({
  externalSubject: '<YOUR_EXTERNAL_SUBJECT>',
  displayName: 'Example visitor',
});
await widget.clearIdentity();

await widget.resetVisitor({
  closeSession: true,
  clearHistory: true,
  clearDraft: true,
  clearIdentity: true,
});

// There is no separate logout method; clear the server association and local state.
await widget.clearIdentity();

Call clearIdentity() or resetVisitor() when the host user logs out or changes accounts. A verified identity change closes the previous visitor session and clears its local conversation continuity before associating the new subject. Closing the panel is not the same as ending visitor continuity.

Identity, consent, suppression, ban, Connection, Workspace, and origin policy remain server-authoritative. The browser must treat missing, malformed, mismatched, expired, revoked, or banned context as a visible failure, not as an anonymous success.