Identity Forwarding
This page covers the Website Widget identify() API. For REST tool configuration (END_USER_IDENTITY), SDK lookup.required, and channel matrices, see Identity forwarding (REST) and Identity resolution (SDK).
Identity Forwarding lets your host application tell Qefro who the website visitor is, so Business Actions can call your APIs in that user’s context. Qefro does not replace your auth system — you own JWT/session issuance.
REST tools with END_USER_IDENTITY receive the forwarded JWT/session on outbound HTTP calls. Backend SDK webhooks receive identity attributes (email, phone, id) — not raw JWT secrets.
Introduction
Implemented in @qefro-ai/widget via:
widget.identify({ id, email?, name?, auth?: { mode, token } })widget.setAuthToken(jwt)— refresh without restartwidget.clearIdentity()— clears local identity and notifiesPOST /api/v1/widget/identity/clear
Auth modes:
| Mode | Token transport |
|---|---|
jwt | Header X-End-User-Token / WS endUserToken |
session | Header X-End-User-Session / WS endUserSession |
none | Profile only (id/email/name) — no bearer secret |
Why it exists
Order lookup, ticket creation, and account mutations must not run as a shared service account when the end user is logged into your product.
Concepts
- Host-owned identity — your IdP / session store
- Forwarded claims — id, email, name + auth material for tool HTTP calls
- Visitor session — separate continuity key; clearing identity does not wipe chat history by default
Architecture
Workflow
Wire identify()
- Authenticate in your app — Issue JWT or session as you already do.
- Call identify() — Pass stable user id + auth.mode/token.
- Configure tools — Business Tools that need user context read forwarded headers/claims.
- Logout — await widget.clearIdentity().
Code examples
widget.identify({
id: user.id,
email: user.email,
name: user.name,
auth: {
mode: 'jwt',
token: userJwt, // from YOUR auth system
},
});
// Later
widget.setAuthToken(refreshedJwt);
await widget.clearIdentity();
Anonymous visitors: do not call identify().
Best practices
- Use a stable opaque user id (not email alone) as
id - Keep JWT lifetimes short; refresh with
setAuthToken - Scope Business Tools to least privilege when identity is present