Identity signing

This reference covers the signed-identity contract for the web widget. For the dashboard-level view of verification, see Verify identity.

The signature object

A signed identity is three strings, produced on your server and handed to the widget.

Field	Description
`kid`	The signing key’s ID, shown in the dashboard
`payload`	Base64-encoded JSON claims (below)
`sig`	Base64-encoded HMAC-SHA256 of the `payload` string, keyed with your signing secret

Payload claims

Claim	Type	Required	Description
`iat`	number	Yes	Issue time in milliseconds since epoch. Signatures older than 24 hours are rejected
`sub`	string	Yes	Must equal the widget’s `channelUserId` (see below)
`email`	string	No	Verified email to attach to the profile
`phone`	string	No	Verified phone to attach to the profile
`name`	string	No	Verified display name

Keep every claim value ASCII. Verification decodes the payload as plain base64 with no UTF-8 step, so a non-ASCII name or email address still verifies but arrives with mangled characters.

The gotcha: sub must equal channelUserId

Verification rejects any signature whose sub claim differs from the widget’s channelUserId. This is the most common integration failure. The widget’s channelUserId is the anonymous ID that embed.js stores in the host page’s localStorage under the key tars_anonymous_id. Read that value on the page, send it to your server, and sign it as sub. Do not sign your own internal ID: the subjects will not match, and verification fails silently for the end user. The widget adopts that anonymous ID only for a fresh session. A widget session that already carries an end-user record or a session token keeps its own channelUserId, which is a generated value the host page cannot read. Check this first when verification returns subject_mismatch for a returning end user.

Signing example

// Server-side (Node)
import crypto from "node:crypto";

const payload = Buffer.from(
  JSON.stringify({
    iat: Date.now(),
    sub: channelUserId, // the tars_anonymous_id value from the browser
    email: user.email,
    name: user.name
  })
).toString("base64");

const sig = crypto
  .createHmac("sha256", process.env.TARS_IDENTITY_SECRET)
  .update(payload)
  .digest("base64");

// Return { kid: "YOUR_KEY_ID", payload, sig } to the browser

Deliver the result to the widget either way.

// At load time, before embed.js runs
window.TarsConfig = {
  convId: "YOUR_AGENT_ID",
  identity: { kid: "YOUR_KEY_ID", payload, sig }
};

// Or mid-session, after the end user signs in
window.TarsWidget.identify({ kid: "YOUR_KEY_ID", payload, sig });

Signing keys and rotation

Manage the key under Settings → Integrations, in the Identity Verification panel. Generate signing key creates the key, and the panel shows its key ID, masked secret, and created date. Regenerate issues a new key immediately. The old key keeps verifying for 24 hours, so rotate your server secret inside that overlap window. Signatures made with a key retired longer than 24 hours are rejected.

Verified data wins

Fields attached through a valid signature are verified. Unverified browser data (plain TarsConfig values) can never overwrite them. A verified match can also merge an anonymous profile into the identified one, keeping earlier conversation history.

Verification failures

Failures are silent for the end user: the conversation continues unverified. Tars records the reason as a security event.

Reason	Cause
`signature_invalid`	Unknown `kid`, expired key, malformed payload, stale `iat`, or a bad HMAC
`subject_mismatch`	`sub` does not equal the widget’s `channelUserId`

Welcome

Core concepts

Guides

Developer

The signature object

Payload claims

The gotcha: sub must equal channelUserId

Signing example

Signing keys and rotation

Verified data wins

Verification failures

​The signature object

​Payload claims

​The gotcha: sub must equal channelUserId

​Signing example

​Signing keys and rotation

​Verified data wins

​Verification failures

​Related pages

The signature object

Payload claims

The gotcha: sub must equal channelUserId

Signing example

Signing keys and rotation

Verified data wins

Verification failures

Related pages