Identity Verification

Identity verification lets your agent know which logged-in user is talking to it. Use it when your agent needs personalized answers or authenticated actions such as order history, returns, billing, or customer profile lookups.

ChatDrift supports two verification modes:

• JWT, recommended for most apps. It verifies the user and can sync contact fields.
• HMAC, useful for lightweight verification when you only need to prove a user ID.

Get your verification secret

In the dashboard, open your agent and go to Integrate. In Identity verification, enable the feature and copy the generated secret.

Store this secret only on your server. Never expose it in browser JavaScript.

JWT mode

Generate a short-lived HS256 JWT on your server. The token must include sub or user_id, and must include exp.

import jwt from "jsonwebtoken"

export async function createChatDriftIdentityToken(user: {
  id: string
  email?: string
  name?: string
  phone?: string
  plan?: string
}) {
  return jwt.sign(
    {
      sub: user.id,
      email: user.email,
      name: user.name,
      phone: user.phone,
      custom_attributes: {
        plan: user.plan,
      },
      exp: Math.floor(Date.now() / 1000) + 60 * 60,
    },
    process.env.CHATDRIFT_WIDGET_IDENTITY_SECRET!,
    { algorithm: "HS256" },
  )
}

Then pass the token to the widget:

const token = await fetch("/api/chatdrift-identity").then((res) => res.text())

widget.identify({
  mode: "jwt",
  token,
  publicAttributes: {
    plan: user.plan,
  },
})

JWT claims such as email, name, phone, and custom_attributes can update the linked contact. Public attributes are visible to the agent context, so do not put secrets or sensitive fields there.

HMAC mode

Generate a SHA-256 HMAC on your server using the logged-in user's stable ID.

import { createHmac } from "node:crypto"

export function createChatDriftUserHash(userId: string) {
  return createHmac("sha256", process.env.CHATDRIFT_WIDGET_IDENTITY_SECRET!)
    .update(userId)
    .digest("hex")
}

Then identify the user:

widget.identify({
  mode: "hmac",
  userId: user.id,
  userHash,
  userMetadata: {
    plan: user.plan,
  },
})

HMAC mode verifies identity but does not create contacts from metadata. To link a contact, create or update a ChatDrift contact whose external user ID is stored as business_id.

Initial page-load identity

You can pass identity in the initial widget options:

import { NexvioWidget } from "@nexvio-ai/widget-js/react"

<NexvioWidget
  options={{
    publicKey: "pk_...",
    identity: {
      mode: "jwt",
      token,
      publicAttributes: { plan: "pro" },
    },
  }}
/>

Logout

When your user logs out, reset the widget identity:

widget.resetUser()

This clears verified identity from the current chat session. Authenticated actions will require the user to identify again.

Security checklist

• Generate JWTs and HMAC hashes only on your server.
• Keep JWT expiration short, preferably under 24 hours.
• Use stable user IDs, not email addresses, for sub, user_id, or userId.
• Do not include sensitive information in publicAttributes or userMetadata.
• Rotate the verification secret if it is exposed.