Features

Identity Verification

Identify signed-in website users with a server-signed JWT and connect their verified profile to MuChat.

Identity verification connects a user who is signed in to your website with their MuChat conversation. Your server signs a JSON Web Token (JWT); the widget sends it to MuChat to verify the user and load the corresponding conversation and profile.

MuChat uses HS256 JWTs and a signing key belonging to the widget channel. The website token in the installation code is public and is different from this secret.

When to Use Identity Verification

Implementation Guide

Prerequisites

Install the chat bubble and have an authentication system that identifies the current user on your server. For a direct iframe, follow the separate iframe identity flow.

Get Your Secret Key

Open the installation panel

In the dashboard, open your agent, go to Deploy, and click Manage on Chat Widget. Open Deploy above the preview and choose Website widget.

Open Identity verification

Expand Identity verification. Copy the Secret key with its copy button. If no key exists, use Show to create it.

Store the key on your server

Save it as MUCHAT_IDENTITY_SECRET in your server environment. Keep it out of client bundles, public environment variables, source control, and URLs.

JWT Implementation

JWT Overview

A JWT contains a header, claims, and a signature. MuChat verifies the signature with this widget channel's key before accepting the identity. It does not encrypt the payload: anyone holding a token can read its contents.

Generating the JWT Payload

JWT payload
{
  "user_id": "user-123",
  "name": "User",
  "email": "user@example.com",
  "iat": 1792886400,
  "exp": 1792890000
}

user_id is required and must be a non-empty string without surrounding whitespace. sub alone does not identify a user. The timestamps above illustrate the format; generate current Unix timestamps in seconds when signing.

Use an immutable account ID, rather than an email address that can change. Optional claims must use the supported names; arbitrary top-level fields and user_metadata are rejected.

Sign the Token on Your Server

Install jsonwebtoken in your server application. Call this helper with the user resolved from your authenticated server session.

create-user-token.js
import jwt from "jsonwebtoken";

export function createUserToken(user) {
  const secret = process.env.MUCHAT_IDENTITY_SECRET;
  if (!secret) throw new Error("Missing identity secret");

  return jwt.sign(
    {
      user_id: String(user.id),
      name: user.name,
      email: user.email
    },
    secret,
    { algorithm: "HS256", expiresIn: "1h" }
  );
}

Your token endpoint must derive the identity from the authenticated server session. Do not sign a user_id, email, or protected profile value supplied by the browser without checking it against that session.

Identifying the User

After window.muchatSDK.run(...) has initialized the SDK, get the token from your server and pass it as a string:

identify-user.js
async function identifyMuchatUser() {
  const response = await fetch("/api/muchat/token", {
    credentials: "same-origin",
    cache: "no-store"
  });
  if (!response.ok) throw new Error("Could not get user token");
  const { token } = await response.json();
  window.$muchat.setUser(token);
}

identifyMuchatUser().catch(console.error);

/api/muchat/token is an endpoint you implement in your application. It is not a MuChat API endpoint. setUser queues the token if the widget is still bootstrapping; its return value is not a promise or proof of successful verification.

When authenticated-only access is enabled, muchat:user-identified fires after successful identification. Listen before calling setUser. In an unrestricted widget, this event is not emitted; inspect the identify request in the browser's Network panel when testing. Errors are reported through muchat:error.

Logging out Users

MuChat has no public logout() method. reset() is ignored for verified users, and destroy() removes the widget without deleting its session cookie.

During your application's logout flow, destroy the widget and remove its cookie before mounting a guest widget or reloading the page:

disconnect-user.js
async function disconnectMuchatUser(websiteToken) {
  await window.$muchat.destroy();
  const name = encodeURIComponent(`mu_conversation_${websiteToken}`);
  const expired = `${name}=; Max-Age=0; Path=/`;
  document.cookie = expired;
  const domain = window.muchatSettings?.baseDomain;
  if (domain) document.cookie = `${expired}; Domain=${domain}`;
}

Pass the websiteToken from the installation code. Complete your application's own logout and reload or initialize the widget for the new authentication state. Identify the new account before allowing it to use authenticated chat. Do not treat closing or hiding the widget as logout.

How Contact Updates Work

The token's profile fields are processed during identification. Omitted fields do not request an update; null profile values are ignored in this flow. A newly signed token can supply updated values, but a higher-trust manual profile edit may take precedence in the merged contact record.

Verified AI context uses the signed claims from the current channel connection. It does not automatically expose every field in the merged contact record. To update a profile, issue a new token and call setUser again; avoid simultaneous calls with different tokens.

Complete JWT Implementation Flow

Generate the token for the signed-in account

Your application authenticates the request, loads the account from its session, and calls the signing helper. Return { "token": "..." } with Cache-Control: private, no-store. Return an unauthorized response for a guest; do not issue a token for an arbitrary ID from query parameters.

Identify the user in the frontend

Initialize the widget once, fetch the token, and call setUser(token). Repeat this on a full page load. For account changes in a single-page app, finish the old widget's teardown before initializing and identifying the new account.

Check access and continuity

Test the same account in a second browser, a different account, an expired token, and logout on a shared device. If you enable authenticated-only access, confirm that guests cannot open the chat and a restored session waits for identification on the new page.

Identity Parameters

ClaimTypeBehavior
user_idstringRequired, stable account ID, up to 512 characters
name, first_name, last_namestringOptional profile names
emailstringOptional valid email address
phone_numberstringOptional phone number in international format
locale, country_codestringOptional profile locale and two-character country code
exp, iat, nbfintegerOptional Unix timestamps in seconds; validated when present
issstringOptional issuer; changes the identity key to iss:user_id, so keep it stable
audstring or string[]If supplied, must include this widget's agent ID
sub, jtistringOptional standard claims; neither replaces user_id

Do not include internal fields such as identifier or avatar_blob_id.

Security & Best Practices

Troubleshooting

Next Steps

MuChat documentation

On this page