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: true and externalId.

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:

ClaimRequiredRules
subYesYour user id. A string (or number), at most 200 characters.
expYesExpiry in unix seconds, at most 10 minutes after iat (or after now, without iat).
iatRecommendedIssued-at in unix seconds. May not be in the future.
emailNoLabels the contact. Lower-cased; ignored if it is not an email address.
nameNoLabels the contact. Cut to 80 characters.
audNoThe 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:

<code>import jwt from "jsonwebtoken"; const token = jwt.sign( { sub: user.id, email: user.email, name: user.name }, process.env.QUANTCX_IDENTITY_SECRET, { algorithm: "HS256", expiresIn: "10m", audience: "YOUR_AGENT_ID" }, );</code>

Or with no dependency, using node:crypto:

<code>import { createHmac } from "node:crypto"; export function quantcxToken(user, secret, agentId) { const now = Math.floor(Date.now() / 1000); const encode = value => Buffer.from(JSON.stringify(value)).toString("base64url"); const body = `${encode({ alg: "HS256", typ: "JWT" })}.${encode({ sub: String(user.id), email: user.email, name: user.name, iat: now, exp: now + 600, aud: agentId, })}`; return `${body}.${createHmac("sha256", secret).update(body).digest("base64url")}`; }</code>

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 iat in the future;
  • an aud naming 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 identify calls 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.