Signed identity
Prove who a signed-in visitor is with a short-lived HS256 JWT from your server. Verified contacts get a badge in the inbox, client-mode answers and verified-only AI Actions.
Anyone can type a name and an email into a chat. Signed identity lets your site prove it instead: your server signs a token for the user who is signed in, the page hands it to the widget, and QuantCX checks it before trusting a word of it.
What Verified changes
- Inbox: the contact and their open conversations are marked Verified; everyone else is Unverified. Your own user id (the token's
sub) is stored with the contact. - AI answers: the AI answers a verified contact as a client, with the brand's client knowledge and client instructions. Unverified visitors are answered as prospects.
- AI Actions: actions marked verified-only are offered to the AI only in conversations with a verified contact.
- Custom apps: the request to your app carries
contact.verified: trueandexternalId.
1. Create the identity secret
In Studio, open the brand's Brand Settings > Security and use Identity verification > Generate secret. The secret starts with qcx_wid_ and is shown once: store it on your server, for example as QUANTCX_IDENTITY_SECRET. Rotate secret replaces it, and the old secret stops working at once. Never sign tokens in the browser.
2. Sign a token on your server
A JWT signed with HS256 and the secret:
| Claim | Required | Rules |
|---|---|---|
sub | Yes | Your user id. A string (or number), at most 200 characters. |
exp | Yes | Expiry in unix seconds, at most 10 minutes after iat (or after now, without iat). |
iat | Recommended | Issued-at in unix seconds. May not be in the future. |
email | No | Labels the contact. Lower-cased; ignored if it is not an email address. |
name | No | Labels the contact. Cut to 80 characters. |
aud | No | The agent id (or an array containing it). If present it must name this brand's agent. |
Clocks may differ by up to one minute. With jsonwebtoken:
Or with no dependency, using node:crypto:
3. Pass it to the widget
<code>// In the page, after the embed snippet (or after the queue stub): QuantCX("identify", { token }); // When the user signs out: QuantCX("logout");</code>Send a fresh token on each page load; it only has to be valid when the widget checks it.
When a token is refused
A refused token is ignored: the visitor simply stays Unverified. QuantCX refuses:
- any algorithm other than HS256, including
none; - a bad signature, or a token that is not a well-formed JWT (or is longer than 4,096 characters);
- a missing or past
exp, or a lifetime longer than 10 minutes; - an
iatin the future; - an
audnaming another agent; - a missing, empty or longer-than-200-character
sub.
Sign-out and shared browsers
QuantCX("logout")forgets the browser's visitor, so the next person starts a new chat.- If a valid token names a different user than the one this browser's visitor was verified as, the widget starts over as a new visitor instead of showing the previous person's conversations.
- Once a visitor is verified, unsigned
identifycalls can no longer relabel them.
Require verified identity
Turn on Require verified identity in the same section to ignore names and emails the widget sends without a valid token, so only your site can label a conversation. Forms the visitor fills in still work.