Identity Verification

Identity verification ties every widget session to a user your backend has already authenticated. With it on, the widget refuses to load without a valid JWT that you signed. With it off, visitors type their own email and name into an identity form.

Turning It On

Open Chat Widgets → [your widget] → Security and turn identity verification on. A JWT signing secret is generated for you.

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(). Whatever it holds travels with the ticket when a conversation escalates 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 other claim you add is stored and lands in the escalation ticket’s metadata, which is how account IDs or plan types reach your support team. What the ticket does with them depends on the integration handling the escalation.

Getting Started

Support

Agents

Knowledge Base

Playground

Chat Widgets

Integrations

Identity Verification

Turning It On

Embed Code with Authentication

Server-Side Token Generation

JWT Claims

​Turning It On

​Embed Code with Authentication

​Server-Side Token Generation

​JWT Claims

Turning It On

Embed Code with Authentication

Server-Side Token Generation

JWT Claims