Signed widget identity

Start on your trusted server

Create a signing secret in Settings / Chat widget / Identity. In Settings / API access, create a separate REST key with widget:identify, select the widget and grant the customer scopes your backend needs. The REST key authenticates your server; the signing secret signs short-lived widget proofs.

When your application user signs in, resolve their stable account ID and TruCom customer ID on your backend. Return only the short-lived identity token to that authenticated customer’s browser.

Request an identity token

POST /widget/identity-tokens takes customer_id, subject and an optional ttl_seconds. The default lifetime is 900 seconds; allowed values are 60–3,600.

The key selects the widget. The first request permanently binds the case-sensitive subject to that customer for that widget. Reusing the subject for a different customer returns identity_subject_conflict. A missing signing configuration returns identity_signing_not_configured.

curl -X POST "https://trucom.app/api/v1/rest/widget/identity-tokens" \
  -H "Authorization: Bearer $TRUCOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"CUSTOMER_PUBLIC_ULID","subject":"account-1042","ttl_seconds":900}'

Give only the proof to the widget

Your own authenticated backend endpoint returns data.identity_token to the signed-in customer. Supply that proof to the JavaScript SDK. It authorizes only history already associated with the signed subject in this widget. It does not grant every CRM conversation merely because an email matches.

Fetch a fresh proof when the previous one expires. Reset the widget on logout or account switch before identifying another customer. Keep this endpoint on your own backend protected by your application’s authentication and CSRF controls.

// Your endpoint derives identity from its authenticated session.
const response = await fetch('/account/support-identity', {
  credentials: 'same-origin', headers: { Accept: 'application/json' }
});
if (!response.ok) throw new Error('Unable to verify support identity');
const { identity_token } = await response.json();
await TruComWidget.identify({ identity_token });

When a customer changes

A subject binding is not an email lookup or an account-merge tool. Keep subject values stable and unique. If a CRM customer has been merged, resolve the active customer and review the existing binding before migrating the integration. Rotating the widget signing secret invalidates previously issued proofs; issue fresh ones.