Identity Verification (JWT)

Why identity verification

Your widget key is public, so on its own it says nothing about which visitor is calling. Without identity verification, anyone could claim to be any user by sending an arbitrary userId and read that user’s support history. For that reason the Halo backend fails closed: any request that names a user (a non-anonymous userId / user_id) is rejected with 403 until your workspace has an Identity Secret, because there is nothing to verify the claim against. Anonymous chat (no userId) works without a secret. Identity verification is the fix: every user-scoped call includes a JWT signed with your Identity Secret. The Halo backend verifies the signature; if it doesn’t match, the call is rejected with 403. The JWT can also carry trusted claims — email, name, role, plan, company_id — that Halo will use without a database lookup. This makes the AI more responsive and lets you prove identity even when the user record hasn’t been pushed to Halo yet.

Two keys, two roles

Halo generates two keys when you set up your project:

Key	Prefix	Where it goes	Purpose
Widget key	`ab_live_...`	Frontend (browser)	Identify your workspace — publishable, safe to expose
Identity secret	`ha_secret_...`	Backend only	Sign JWTs for identity verification

Copy your widget key from Setup > Install. Generate your identity secret under Settings > Security. Never confuse them — exposing the identity secret in client code defeats the entire system.

JWT payload

The JWT must include user_id and may include any additional claims:

{
  "user_id": "user_123",
  "email": "jane@acme.com",
  "name": "Jane Doe",
  "company_id": "company_456",
  "role": "admin",
  "plan": "pro",
  "exp": 1716242622
}

Claim	Required?	Notes
`user_id`	Required	Must match the `userId` passed to Halo from the frontend
`exp`	Recommended	Standard JWT expiration (Unix timestamp)
`email`, `name`	Recommended	Fill in the contact’s email/name whenever `identify()` runs without those traits, and power lead-to-user conversion
All other claims	Optional	Used as trusted user data by the AI

Algorithm: HS256. The signing key is your Identity Secret (ha_secret_...).

Server-side: generate the JWT

Sign the JWT on your backend whenever you serve a page that loads the Halo widget. Pass the resulting token to your frontend (via the page HTML, an API endpoint, or session state).

const jwt = require("jsonwebtoken");

function generateUserToken(user, secretKey) {
  return jwt.sign(
    {
      user_id: user.id,
      email: user.email,
      name: user.name,
      role: user.role,
      company_id: user.companyId,
    },
    secretKey,
    { algorithm: "HS256", expiresIn: "24h" }
  );
}

const token = generateUserToken(currentUser, process.env.HALOAGENTS_SECRET_KEY);

import jwt
import time
import os

def generate_user_token(user, secret_key):
    payload = {
        "user_id": user["id"],
        "email": user.get("email"),
        "name": user.get("name"),
        "role": user.get("role"),
        "company_id": user.get("company_id"),
        "exp": int(time.time()) + 86400,
    }
    return jwt.encode(payload, secret_key, algorithm="HS256")

token = generate_user_token(current_user, os.environ["HALOAGENTS_SECRET_KEY"])

use Firebase\JWT\JWT;

function generateUserToken(array $user, string $secretKey): string {
    $payload = [
        "user_id" => $user["id"],
        "email" => $user["email"] ?? null,
        "name" => $user["name"] ?? null,
        "role" => $user["role"] ?? null,
        "company_id" => $user["company_id"] ?? null,
        "exp" => time() + 86400,
    ];
    return JWT::encode($payload, $secretKey, "HS256");
}

$token = generateUserToken($currentUser, getenv("HALOAGENTS_SECRET_KEY"));

require "jwt"

def generate_user_token(user, secret_key)
  payload = {
    user_id: user[:id],
    email: user[:email],
    name: user[:name],
    role: user[:role],
    company_id: user[:company_id],
    exp: Time.now.to_i + 86_400,
  }
  JWT.encode(payload, secret_key, "HS256")
end

token = generate_user_token(current_user, ENV["HALOAGENTS_SECRET_KEY"])

If you expose JWT minting through an HTTP route (for getUserToken or SPA refresh), log errors in your catch blocks before returning 500. Empty catch {} blocks make production debugging much harder.

// Example route handler shape (adapt to your framework)
async function haloTokenHandler(request) {
  try {
    const user = await getAuthenticatedUser(request);
    if (!user) return respond({ error: "Unauthorized" }, 401);
    const token = generateUserToken(user, process.env.HALOAGENTS_SECRET_KEY);
    return respond({ token }, 200);
  } catch (error) {
    console.error("Failed to generate Halo token", error);
    return respond({ error: "Failed to generate token" }, 500);
  }
}

Client-side: pass the token

Pass the JWT as userToken when initializing Halo. Always include userTraits with at least name and email so users show up correctly in your inbox:

<script src="https://cdn.haloagents.ai/sdk/latest/haloagents.umd.js"></script>
<script>
  window.HaloAgents.init({
    orgId: "your-org-id",
    apiKey: "ab_live_xxxxxxxxxxxxxxxx",
    userId: "user_123",
    userToken: "YOUR_JWT_TOKEN",
    userTraits: {
      name: "Jane Doe",
      email: "jane@acme.com",
    },
  });
</script>

For server-rendered pages, you can inject the token directly:

<script>
  window.HaloAgents.init({
    orgId: "your-org-id",
    apiKey: "ab_live_xxxxxxxxxxxxxxxx",
    userId: "<?= $user->id ?>",
    userToken: "<?= $haloToken ?>",
    userTraits: {
      name: "<?= $user->name ?>",
      email: "<?= $user->email ?>",
    },
  });
</script>

Token refresh

JWTs expire. The SDK supports two refresh patterns:

Recommended: `getUserToken` (SDK 0.9.0+)

Provide an async callback that fetches a fresh JWT from your backend. The SDK calls it when the static userToken from init() is missing or near expiry (5-minute skew). The identity secret stays on your server.

window.HaloAgents.init({
  orgId: "your-org-id",
  apiKey: "ab_live_xxxxxxxxxxxxxxxx",
  userId: "user_123",
  userToken: initialJwtFromYourServer,
  getUserToken: async () => {
    const res = await fetch("/api/haloagents-token");
    const { token } = await res.json();
    return token;
  },
  onIdentityExpired: ({ reason, expiresAt, message }) => {
    // reason: "expired" | "missing" | "rejected"
    // Fires once; user-scoped requests pause until a fresh token arrives.
    refreshSessionAndReIdentify();
  },
});

When identity fails (expired, missing, or rejected with 403), the SDK stops sending known-expired JWTs and pauses user-scoped polling until getUserToken or identify(..., { userToken }) succeeds. Server-side enforce mode is unchanged.

Manual: `identify()` rotation

You can still rotate tokens yourself on session refresh:

const newToken = await fetch("/api/halo-token").then(r => r.json()).then(d => d.token);
HaloAgents.getInstance()?.identify(userId, traits, { userToken: newToken });

A common pattern: generate the JWT with exp matching your app’s session length (e.g. 24 hours) and refresh both at the same time.

Verification modes (dashboard)

After generating an identity secret under Settings > Security, choose how strictly Halo validates tokens:

Mode	Behavior
Off	No verification
Monitor	Validate when present; log warnings but allow requests. Default when you generate a secret
Enforce	Reject unverified authenticated requests with 403

Stay in monitor while integrating. The Security page tracks production health and unlocks enforce only after verified requests succeed in the last 24 hours with no failures.

Server-to-server calls

The same token applies to direct REST API calls from your backend. For example, POST /api/sdk/chat accepts user_token:

await fetch("https://api.haloagents.ai/api/sdk/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer ab_live_xxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({
    user_id: "user_123",
    user_token: serverGeneratedJWT,
    message: "...",
  }),
});

If a non-anonymous user_id is provided without a valid user_token, the request returns 403. The same 403 is returned when the workspace has no Identity Secret at all; the error body tells you to generate one under Settings > Security.

Best practices

Always pass name and email in userTraits (during init), via identify(), or as JWT claims. Since SDK 0.10, init() persists userTraits automatically, and verified email/name claims fill in the contact even when no traits are sent. Without any of these, users show as “Anonymous” in tickets and conversations.
Set exp to match your session length — 24 hours is a common default. Shorter is more secure.
Refresh tokens with getUserToken (preferred) or identify(..., { userToken }) on session refresh.
Wire onIdentityExpired so your app refreshes credentials when enforce mode rejects stale JWTs.
Include trusted claims — the more claims (email, role, plan, company_id), the more personalized the AI without extra database lookups.
Never expose the Identity Secret client-side — keep it in environment variables, never in your HTML or frontend bundle.

Where to go next

Identify Users

The basic identification flow before adding verification.

API Reference

Server-to-server calls with JWT.

Security Settings

Generate your identity secret and set verification mode.

Getting Started

Web Widget

AI Agents

Ask AI

Inbox

Knowledge

Channels

Help Center

Contacts & Companies

Outreach

Settings

Advanced

Identity Verification (JWT)

Why identity verification

Two keys, two roles

JWT payload

Server-side: generate the JWT

Client-side: pass the token

Token refresh

Recommended: `getUserToken` (SDK 0.9.0+)

Manual: `identify()` rotation

Verification modes (dashboard)

Server-to-server calls

Best practices

Where to go next

Identify Users

API Reference

Security Settings

​Why identity verification

​Two keys, two roles

​JWT payload

​Server-side: generate the JWT

​Client-side: pass the token

​Token refresh

​Recommended: getUserToken (SDK 0.9.0+)

​Manual: identify() rotation

​Verification modes (dashboard)

​Server-to-server calls

​Best practices

​Where to go next

Identify Users

API Reference

Security Settings

Why identity verification

Two keys, two roles

JWT payload

Server-side: generate the JWT

Client-side: pass the token

Token refresh

Recommended: `getUserToken` (SDK 0.9.0+)

Manual: `identify()` rotation

Verification modes (dashboard)

Server-to-server calls

Best practices

Where to go next