Skip to main content
Both the chat widget and voice web-call widget accept the same signed identity. Keep the signing secret on your server.

Signature object

Claims

UTF-8 names and values are supported, including accented and non-Latin characters. Null optional identity fields are treated as absent. A signature is accepted for 24 hours. iat can be up to 60 seconds ahead of the server clock. sub must be the widget’s ID from tars_anonymous_id in the host page’s localStorage. Do not substitute your own account ID.

Three-step signing recipe

Read the widget ID in the browser. Send it to your server with the signed-in end user’s details. Your server creates the payload and signature. Return only kid, payload and sig to the browser.
The recipe is the same as How to sign a visitor in the dashboard. Add phone to the claims if required.

Deliver the identity

Call TarsWidget.identify after the widget loads, or set TarsConfig.identity before loading embed.js. An identity sent after load updates an open chat conversation and applies to the next voice web-call session. It does not interrupt a live call.

Signing keys and rotation

Open Settings → Integrations → Signing secrets, then the Identity verification card. Generate signing key creates a current key. Copy its secret to your server. Rotate key creates a replacement and lists the retiring key with its end time. The retiring key remains valid for 24 hours. Another rotation is refused until that overlap ends. Copy works on both current and retiring keys, and each copy is audited. Remove keys removes both immediately. Signatures made with them no longer verify.

Verification failures

When signatures fail, the card shows the failed checks from the last 24 hours, up to 100+, and the most common reason. The audit log records each failure reason. An invalid identity does not grant access to an existing conversation. The widget can continue with an unverified session.

Known limits

An older chat session with an existing record or token keeps its generated channelUserId until it ends. Signing the host page’s anonymous ID for that older session returns subject_mismatch. End that session before trying again. If localStorage is unavailable, the host page cannot store tars_anonymous_id. Verification cannot work on that page.