> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Identity signing
> Sign end-user identity server-side with HMAC-SHA256 so the widget can trust who is chatting.
export const img = {
activity: {
activityTimeline: "/docs/guides/activity/images/activity-timeline.png",
capturedVariablesPanel: "/docs/guides/activity/images/captured-variables-panel.png",
dataViewCards: "/docs/guides/activity/images/data-view-cards.png",
exportDataDialog: "/docs/guides/activity/images/export-data-dialog.png",
tasksPanelExportReady: "/docs/guides/activity/images/tasks-panel-export-ready.png"
},
analytics: {
analyticsOverview: "/docs/guides/analytics/images/analytics-overview.png",
exploreGallery: "/docs/guides/analytics/images/explore-gallery.png",
exploreTab: "/docs/guides/analytics/images/explore-tab.png",
goalForm: "/docs/guides/analytics/images/goal-form.png",
goalsTab: "/docs/guides/analytics/images/goals-tab.png",
improveDiagnostics: "/docs/guides/analytics/images/improve-diagnostics.png",
improveTab: "/docs/guides/analytics/images/improve-tab.png",
teamTab: "/docs/guides/analytics/images/team-tab.png"
},
billing: {
billingOverview: "/docs/guides/billing/images/billing-overview.png",
buyConversationsDialog: "/docs/guides/billing/images/buy-conversations-dialog.png",
buySeatsDialog: "/docs/guides/billing/images/buy-seats-dialog.png",
livechatSeatsTab: "/docs/guides/billing/images/livechat-seats-tab.png",
organizationDeletionLifecycle: "/docs/guides/billing/images/organization-deletion-lifecycle.svg",
organizationSwitcher: "/docs/guides/billing/images/organization-switcher.png",
rolesAndAccessMatrix: "/docs/guides/billing/images/roles-and-access-matrix.png"
},
building: {
agentBehaviorGuardrails: "/docs/guides/building/images/agent-behavior-guardrails.png",
agentCardMenu: "/docs/guides/building/images/agent-card-menu.png",
agentConfigure: "/docs/guides/building/images/agent-configure.png",
agentExitRoutesDialog: "/docs/guides/building/images/agent-exit-routes-dialog.png",
agentLibrary: "/docs/guides/building/images/agent-library.png",
agentModelParameters: "/docs/guides/building/images/agent-model-parameters.png",
aiAgentGambitLoop: "/docs/guides/building/images/ai-agent-gambit-loop.svg",
builderBasics: "/docs/guides/building/images/builder-basics.png",
builderConnectHandlePanel: "/docs/guides/building/images/builder-connect-handle-panel.png",
builtInToolsDialog: "/docs/guides/building/images/built-in-tools-dialog.png",
configureDebugTab: "/docs/guides/building/images/configure-debug-tab.png",
configureLanguage: "/docs/guides/building/images/configure-language.png",
configureNotifications: "/docs/guides/building/images/configure-notifications.png",
createAgentDialog: "/docs/guides/building/images/create-agent-dialog.png",
draftPublishRollbackPinning: "/docs/guides/building/images/draft-publish-rollback-pinning.svg",
draftSwitcherChip: "/docs/guides/building/images/draft-switcher-chip.png",
duplicateAgentDialog: "/docs/guides/building/images/duplicate-agent-dialog.png",
flowConditions: "/docs/guides/building/images/flow-conditions.png",
gambitPalette: "/docs/guides/building/images/gambit-palette.png",
gambits: {
gambitAiAgent: "/docs/guides/building/gambits/images/gambit-ai-agent.png",
gambitApiCall: "/docs/guides/building/gambits/images/gambit-api-call.png",
gambitAutoSuggestion: "/docs/guides/building/gambits/images/gambit-auto-suggestion.png",
gambitButton: "/docs/guides/building/gambits/images/gambit-button.png",
gambitCard: "/docs/guides/building/gambits/images/gambit-card.png",
gambitChannel: "/docs/guides/building/gambits/images/gambit-channel.png",
gambitCustomCode: "/docs/guides/building/gambits/images/gambit-custom-code.png",
gambitDateTime: "/docs/guides/building/gambits/images/gambit-date-time.png",
gambitGeoLocation: "/docs/guides/building/gambits/images/gambit-geo-location.png",
gambitLanguage: "/docs/guides/building/gambits/images/gambit-language.png",
gambitLiveChat: "/docs/guides/building/gambits/images/gambit-live-chat.png",
gambitMediaUpload: "/docs/guides/building/gambits/images/gambit-media-upload.png",
gambitNoInput: "/docs/guides/building/gambits/images/gambit-no-input.png",
gambitRedirect: "/docs/guides/building/gambits/images/gambit-redirect.png",
gambitStarRating: "/docs/guides/building/gambits/images/gambit-star-rating.png",
gambitStartAndEnd: "/docs/guides/building/gambits/images/gambit-start-and-end.png",
gambitText: "/docs/guides/building/gambits/images/gambit-text.png",
gambitTrigger: "/docs/guides/building/gambits/images/gambit-trigger.png"
},
languagesTranslateGambit: "/docs/guides/building/images/languages-translate-gambit.png",
languageSystemMessages: "/docs/guides/building/images/language-system-messages.png",
newDraftDialog: "/docs/guides/building/images/new-draft-dialog.png",
outputComponentsGrid: "/docs/guides/building/images/output-components-grid.png",
publishDialog: "/docs/guides/building/images/publish-dialog.png",
systemPromptDialog: "/docs/guides/building/images/system-prompt-dialog.png",
testModeEventLog: "/docs/guides/building/images/test-mode-event-log.png",
testModePanel: "/docs/guides/building/images/test-mode-panel.png",
validationProblemsPanel: "/docs/guides/building/images/validation-problems-panel.png",
variablePickerPanel: "/docs/guides/building/images/variable-picker-panel.png",
variablePillInserted: "/docs/guides/building/images/variable-pill-inserted.png",
versionsDraftsPanel: "/docs/guides/building/images/versions-drafts-panel.png"
},
campaigns: {
campaignFlavorsTriggers: "/docs/guides/campaigns/images/campaign-flavors-triggers.svg",
campaignReplyRouting: "/docs/guides/campaigns/images/campaign-reply-routing.svg",
campaignSendAnatomy: "/docs/guides/campaigns/images/campaign-send-anatomy.svg",
createACampaign: "/docs/guides/campaigns/images/create-a-campaign.png",
walletReserveSettleRefund: "/docs/guides/campaigns/images/wallet-reserve-settle-refund.svg",
webhookCampaignContractLocking: "/docs/guides/campaigns/images/webhook-campaign-contract-locking.svg",
webhookCampaignLifecycleStates: "/docs/guides/campaigns/images/webhook-campaign-lifecycle-states.svg",
webhookCampaignOneCallOneDelivery: "/docs/guides/campaigns/images/webhook-campaign-one-call-one-delivery.svg"
},
channels: {
distributeWhatsappConnect: "/docs/guides/channels/images/distribute-whatsapp-connect.png",
whatsappConnectDialogWaiting: "/docs/guides/channels/images/whatsapp-connect-dialog-waiting.png",
whatsappEmptyState: "/docs/guides/channels/images/whatsapp-empty-state.png"
},
deploy: {
bridgeEventGambitSection: "/docs/guides/deploy/images/bridge-event-gambit-section.png",
deploymentSurfacesAndChannels: "/docs/guides/deploy/images/deployment-surfaces-and-channels.svg",
designAgentTab: "/docs/guides/deploy/images/design-agent-tab.png",
designLauncherTab: "/docs/guides/deploy/images/design-launcher-tab.png",
embedIframeTab: "/docs/guides/deploy/images/embed-iframe-tab.png",
embedTheWidget: "/docs/guides/deploy/images/embed-the-widget.png",
mobileAppIntegration: "/docs/guides/deploy/images/mobile-app-integration.png",
onYourDomain: "/docs/guides/deploy/images/on-your-domain.png",
shareYourAgentLink: "/docs/guides/deploy/images/share-your-agent-link.png"
},
developer: {
api: {
channelSendTemplateVsMessage: "/docs/developer/api/images/channel-send-template-vs-message.svg",
endUsers: {
endUsersListCursorPagination: "/docs/developer/api/end-users/images/end-users-list-cursor-pagination.svg"
},
triggerCallConversationLifecycle: "/docs/developer/api/images/trigger-call-conversation-lifecycle.svg"
},
developerSurfacesMap: "/docs/developer/images/developer-surfaces-map.svg",
embed: {
embedConfigToWidgetContext: "/docs/developer/embed/images/embed-config-to-widget-context.svg",
hostPageBridgeFlow: "/docs/developer/embed/images/host-page-bridge-flow.svg",
identitySigningFlow: "/docs/developer/embed/images/identity-signing-flow.svg",
scriptVsIframeEmbed: "/docs/developer/embed/images/script-vs-iframe-embed.svg"
},
mobile: {
bridgeMessageProtocol: "/docs/developer/mobile/images/bridge-message-protocol.svg",
webviewBridgeArchitecture: "/docs/developer/mobile/images/webview-bridge-architecture.svg"
}
},
endUsers: {
anonymousToIdentifiedProfile: "/docs/guides/end-users/images/anonymous-to-identified-profile.svg",
bulkActionBar: "/docs/guides/end-users/images/bulk-action-bar.png",
campaignConsentGate: "/docs/guides/end-users/images/campaign-consent-gate.svg",
consentPerChannelStates: "/docs/guides/end-users/images/consent-per-channel-states.svg",
dynamicVsStaticSegments: "/docs/guides/end-users/images/dynamic-vs-static-segments.svg",
endUserDirectory: "/docs/guides/end-users/images/end-user-directory.png",
endUserProfileAcrossChannels: "/docs/guides/end-users/images/end-user-profile-across-channels.svg",
endUserProfilePanes: "/docs/guides/end-users/images/end-user-profile-panes.png",
profileMergeAndTakeoverProtection: "/docs/guides/end-users/images/profile-merge-and-takeover-protection.svg",
segmentBuilder: "/docs/guides/end-users/images/segment-builder.png",
segmentsPage: "/docs/guides/end-users/images/segments-page.png"
},
getStarted: {
agentStates: "/docs/get-started/images/agent-states.svg",
buildToLivePath: "/docs/get-started/images/build-to-live-path.svg",
dashboardSidebarMap: "/docs/get-started/images/dashboard-sidebar-map.png",
organizationOwnershipAndRoles: "/docs/get-started/images/organization-ownership-and-roles.svg",
quickstart: {
step1CreateYourAccount: "/docs/get-started/images/quickstart/step-1-create-your-account.png",
step3ConnectTheAiAgent: "/docs/get-started/images/quickstart/step-3-connect-the-ai-agent.png",
step4TestMode: "/docs/get-started/images/quickstart/step-4-test-mode.png"
},
quickstartCanvas: "/docs/get-started/images/quickstart-canvas.png"
},
knowledge: {
addASource: "/docs/guides/knowledge/images/add-a-source.png",
addRetrieverPicker: "/docs/guides/knowledge/images/add-retriever-picker.png",
attachKnowledgeGambit: "/docs/guides/knowledge/images/attach-knowledge-gambit.png",
configureARetriever: "/docs/guides/knowledge/images/configure-a-retriever.png",
createKnowledgeBaseDialog: "/docs/guides/knowledge/images/create-knowledge-base-dialog.png",
customRetrieverDialog: "/docs/guides/knowledge/images/custom-retriever-dialog.png",
datasetTab: "/docs/guides/knowledge/images/dataset-tab.png",
documentChangeReindexLifecycle: "/docs/guides/knowledge/images/document-change-reindex-lifecycle.svg",
documentsTabPreview: "/docs/guides/knowledge/images/documents-tab-preview.png",
importAWebsite: "/docs/guides/knowledge/images/import-a-website.png",
kbList: "/docs/guides/knowledge/images/kb-list.png",
retrieverIndexStates: "/docs/guides/knowledge/images/retriever-index-states.svg",
retrieverQueryPipeline: "/docs/guides/knowledge/images/retriever-query-pipeline.svg",
standardVsParentChildChunking: "/docs/guides/knowledge/images/standard-vs-parent-child-chunking.svg",
syncManagement: "/docs/guides/knowledge/images/sync-management.png",
testRetriever: "/docs/guides/knowledge/images/test-retriever.png"
},
liveChat: {
agentWorkspace: "/docs/guides/live-chat/images/agent-workspace.png",
assignedAgentPicker: "/docs/guides/live-chat/images/assigned-agent-picker.png",
automaticAssignmentRouting: "/docs/guides/live-chat/images/automatic-assignment-routing.svg",
availabilityDropdown: "/docs/guides/live-chat/images/availability-dropdown.png",
cannedResponses: "/docs/guides/live-chat/images/canned-responses.png",
composerPreferences: "/docs/guides/live-chat/images/composer-preferences.png",
copilotPanel: "/docs/guides/live-chat/images/copilot-panel.png",
filterConversationsDialog: "/docs/guides/live-chat/images/filter-conversations-dialog.png",
inboxAnalyticsTab: "/docs/guides/live-chat/images/inbox-analytics-tab.png",
inboxAvailabilityTab: "/docs/guides/live-chat/images/inbox-availability-tab.png",
inboxesSettings: "/docs/guides/live-chat/images/inboxes-settings.png",
inboxRoutingTab: "/docs/guides/live-chat/images/inbox-routing-tab.png",
labelsSettings: "/docs/guides/live-chat/images/labels-settings.png",
newAttributeDialog: "/docs/guides/live-chat/images/new-attribute-dialog.png",
newCannedResponseDialog: "/docs/guides/live-chat/images/new-canned-response-dialog.png",
notificationPreferences: "/docs/guides/live-chat/images/notification-preferences.png",
notificationsPage: "/docs/guides/live-chat/images/notifications-page.png",
pickupTargetCard: "/docs/guides/live-chat/images/pickup-target-card.png",
resolveMenu: "/docs/guides/live-chat/images/resolve-menu.png",
searchDialog: "/docs/guides/live-chat/images/search-dialog.png",
seatGateConversation: "/docs/guides/live-chat/images/seat-gate-conversation.png",
seatsSettings: "/docs/guides/live-chat/images/seats-settings.png",
workTheInbox: "/docs/guides/live-chat/images/work-the-inbox.png"
},
security: {
addOpenRouterKeyDialog: "/docs/guides/security/images/add-open-router-key-dialog.png",
auditChainVerified: "/docs/guides/security/images/audit-chain-verified.png",
auditEventDrawer: "/docs/guides/security/images/audit-event-drawer.png",
auditExportDialog: "/docs/guides/security/images/audit-export-dialog.png",
auditLogViewer: "/docs/guides/security/images/audit-log-viewer.png",
auditRecordLifecycle: "/docs/guides/security/images/audit-record-lifecycle.svg",
logPrivacyRedactionEnabled: "/docs/guides/security/images/log-privacy-redaction-enabled.png",
modelProviderEmptyState: "/docs/guides/security/images/model-provider-empty-state.png",
privacySettings: "/docs/guides/security/images/privacy-settings.png",
siemConnectWizard: "/docs/guides/security/images/siem-connect-wizard.png",
supportActorMasking: "/docs/guides/security/images/support-actor-masking.svg"
},
tools: {
addToolModal: "/docs/guides/tools/images/add-tool-modal.png",
addToolsPanel: "/docs/guides/tools/images/add-tools-panel.png",
codekitActionEditor: "/docs/guides/tools/images/codekit-action-editor.png",
codekitConnectToolkitsDialog: "/docs/guides/tools/images/codekit-connect-toolkits-dialog.png",
codekitSchemaDialog: "/docs/guides/tools/images/codekit-schema-dialog.png",
codekitToolkit: "/docs/guides/tools/images/codekit-toolkit.png",
codekitToolkitAnatomy: "/docs/guides/tools/images/codekit-toolkit-anatomy.svg",
createActionDialog: "/docs/guides/tools/images/create-action-dialog.png",
createCodekitDialog: "/docs/guides/tools/images/create-codekit-dialog.png",
responseFilteringDialog: "/docs/guides/tools/images/response-filtering-dialog.png",
toolGambitEditorAgentMode: "/docs/guides/tools/images/tool-gambit-editor-agent-mode.png",
toolGambitEditorWorkflowMode: "/docs/guides/tools/images/tool-gambit-editor-workflow-mode.png",
toolkitDetail: "/docs/guides/tools/images/toolkit-detail.png",
toolsConnected: "/docs/guides/tools/images/tools-connected.png",
toolsDirectory: "/docs/guides/tools/images/tools-directory.png",
viewActionsModal: "/docs/guides/tools/images/view-actions-modal.png",
workflowModeResponse: "/docs/guides/tools/images/workflow-mode-response.png"
}
};
This reference covers the signed-identity contract for the web widget. For the dashboard-level view of verification, see [Verify identity](/docs/guides/end-users/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
```js theme={null}
// 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.
```js theme={null}
// 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` |
## Related pages
* [Embed script and TarsConfig](/docs/developer/embed/script-and-config)
* [Widget JS API](/docs/developer/embed/widget-js-api)
* [Verify identity](/docs/guides/end-users/verify-identity)