Identity Verification

Identity verification lets you authenticate users before they interact with the chat widget. When enabled, users must be authenticated via a JWT signed by your backend — the widget will not load without a valid token. When disabled, the widget shows an identity form where visitors enter their email and name.

Enabling Identity Verification

Toggle identity verification on from the widget configuration page under Chat Widgets > Identity Verification. Once enabled, a JWT signing secret is generated automatically.

Use the signing secret on your backend to generate JWTs. Never expose it in frontend code.

Embed Code with Authentication

When identity verification is enabled, use data-disable-autoboot and call Decimal.boot() with the signed token:

<script>
  (function() {
    var s = document.createElement('script');
    s.src = 'https://app.getdecimal.ai/widget/v1/widget.js';
    s.setAttribute('data-widget-id', 'YOUR_WIDGET_ID');
    s.setAttribute('data-public-config', 'YOUR_CONFIG_TOKEN');
    s.setAttribute('data-disable-autoboot', '');
    s.async = true;
    s.onload = function() {
      // Fetch token from YOUR backend (not Decimal)
      fetch('/api/your-auth-endpoint')
        .then(r => r.json())
        .then(data => {
          Decimal.boot({ user_token: data.token });
        });
    };
    document.head.appendChild(s);
  })();
</script>

The key differences from the standard embed code:

data-disable-autoboot prevents the widget from loading until a token is provided.
Decimal.boot({ user_token }) initializes the widget with the signed JWT.

You can also pass metadata to Decimal.boot() or update it later with Decimal.update() — metadata is included when escalating to a human.

Server-Side Token Generation

Token generation must happen on your backend server where the secret remains secure.

import jwt from 'jsonwebtoken';

const JWT_SECRET = process.env.DECIMAL_JWT_SECRET;

const token = jwt.sign(
  {
    email: 'user@example.com',        // required
    name: 'Jane Doe',                 // optional
    disable_escalation: false,        // optional
  },
  JWT_SECRET,
  { algorithm: 'HS256', expiresIn: '1h' }
);

import jwt
import os
from datetime import datetime, timedelta, timezone

JWT_SECRET = os.environ["DECIMAL_JWT_SECRET"]
now = datetime.now(timezone.utc)

token = jwt.encode(
    {
        "email": "user@example.com",      # required
        "name": "Jane Doe",               # optional
        "disable_escalation": False,      # optional
        "iat": now,
        "exp": now + timedelta(hours=1),
    },
    JWT_SECRET,
    algorithm="HS256"
)

JWT Claims

Claim	Required	Type	Description
`email`	Yes	string	User’s email address.
`exp`	Yes	number	Token expiration timestamp (Unix seconds). Recommended: 1 hour max.
`name`	No	string	Display name shown in chat.
`disable_escalation`	No	boolean	Set to `true` to prevent this user from escalating to human support.

Any additional claims are stored and included in escalation ticket metadata. This is useful for passing context like account IDs or plan types to your support team. Additional claims may also be available depending on your escalation integration — see the relevant integration docs for details.

​Enabling Identity Verification

​Embed Code with Authentication

​Server-Side Token Generation

​JWT Claims

Enabling Identity Verification

Embed Code with Authentication

Server-Side Token Generation

JWT Claims