Signed identity

By default, anything you pass to SiteTrellis('identify', ...) comes from the visitor's browser, so the agent treats it as self-reported: a visitor can type any name or email into the console. Signed identity fixes that for logged-in users. Your own server signs a short-lived token that says who the user is, your page hands the token to the widget, and SiteTrellis verifies the signature with a secret only you and SiteTrellis know. Verified details are then marked as trusted in the inbox and in leads, and the agent can use them in prompts and tools.

What you get#

• A Verified badge on the conversation, with the user id, name, email and attributes you signed, shown apart from anything self-reported. The visitor label in the inbox prefers the verified name.
• Trusted variables in prompts and custom tools: {{verified.user_id}}, {{verified.name}}, {{verified.email}} and {{verified.NAME}} for each attribute you signed. They are empty for anonymous visitors, and never mixed into the self-reported {{visitor.NAME}} values.
• Verified leads. A lead captured in a verified chat is flagged and carries the user id.

Set it up#

1. Open Sites, choose your site and open the Signed identity tab. Choose Create identity secret and copy it. It is shown once and stored encrypted; keep it in your server configuration, never in page code.
2. On your server, create a token for the logged-in user on every page view (samples in PHP, Node.js and Python are on that tab and in the public API reference).
3. Print the token into the page and pass it to the widget as the second argument of identify.

<script>
  // "token" is created by your server for this page view
  SiteTrellis('identify', { name: 'Ada Lovelace', email: '[email protected]' }, 'eyJhbGciOi...');
</script>

Call SiteTrellis('reset') when the user logs out, so the next person on the same browser starts a fresh conversation.

The token#

The token is a standard JWT signed with HMAC-SHA256 (algorithm HS256), so any JWT library can create it. Any other algorithm, including none, is refused.

How it is protected#

• The signature is compared in constant time, and a token that is wrong, expired or not yet valid is rejected without affecting the chat. Listen with SiteTrellis('on', 'identity', fn) to see why.
• The first visitor that presents a token owns it. The same token from another browser is refused, so a copied token is useless once the real user's page has used it. Keep the expiry short anyway.
• If a different user signs in on the same browser, a new conversation starts for them. They never see the previous person's messages.
• Rotate the secret from the same tab. The previous secret keeps working for 24 hours so pages that are already open are not broken, unless you tick the box to stop accepting it at once. Rotating or turning it off is recorded in the audit log.
• Verified values are still data for the AI, not instructions. In custom tools, {{verified.user_id}} is safe to use to decide whose data to return; {{visitor.NAME}} never is.