Widget Identity

When you verify a user’s identity, the agent can access personalized data and perform privileged actions. The widget supports two methods: passing identity at initialization and programmatic JWT identification.

Identity at initialization

Pass the user object when initializing the widget. The widget calls the HMAC verification endpoint automatically:

<script>
  AgenticTrust.initAsync({
    apiUrl: "https://platform.agentictrust.com/api/v1",
    apiKey: "lum_pk_your_api_key",
    user: {
      id: "user-42",
      email: "user@example.com",
      name: "Jane Doe",
      hmac: "hex_sha256_signature"
    }
  });
</script>

The hmac value must be computed on your backend. See Identity Verification for server-side signing examples.

JWT identification

Use identify() to verify the user with a JWT token after the widget has initialized:

AgenticTrust.identify("eyJhbGciOiJIUzI1NiIs...");

The token must be signed with your project’s HMAC secret using HS256. Required claim: sub (user ID). Optional claims: email, name.

Auto-refresh tokens

For long-lived sessions, set up automatic token refresh so the identity stays valid:

AgenticTrust.setIdentityTokenFetcher(async () => {
  const res = await fetch("/api/agentic-trust/identity-token");
  if (!res.ok) return null;
  const data = await res.json();
  return data.token;
});

The widget calls your fetcher when the current token expires and re-identifies the user automatically.

Backend token endpoint

Here’s an example backend endpoint that issues identity tokens:

import jwt from "jsonwebtoken";

app.get("/api/agentic-trust/identity-token", (req, res) => {
  if (!req.user) return res.status(401).json({ error: "Not authenticated" });

  const token = jwt.sign(
    { sub: req.user.id, email: req.user.email, name: req.user.name },
    process.env.AGENTIC_TRUST_HMAC_SECRET,
    { algorithm: "HS256", expiresIn: "1h" }
  );

  res.json({ token });
});

import jwt
from flask import request, jsonify

@app.route("/api/agentic-trust/identity-token")
def identity_token():
    if not current_user.is_authenticated:
        return jsonify(error="Not authenticated"), 401

    token = jwt.encode(
        {"sub": current_user.id, "email": current_user.email, "name": current_user.name},
        os.environ["AGENTIC_TRUST_HMAC_SECRET"],
        algorithm="HS256",
    )

    return jsonify(token=token)

Verification flow

Your Backend                Widget                  Agentic Trust API
    │                         │                           │
    │  sign JWT / compute HMAC│                           │
    │◄────────────────────────│                           │
    │  return token/signature │                           │
    │────────────────────────►│                           │
    │                         │  POST /identity/verify    │
    │                         │  or /identity/identify    │
    │                         │──────────────────────────►│
    │                         │  { verified: true }       │
    │                         │◄──────────────────────────│

Getting Started

Features

Widget Integration

Identity at initialization

JWT identification

Auto-refresh tokens

Backend token endpoint

Verification flow

​Identity at initialization

​JWT identification

​Auto-refresh tokens

​Backend token endpoint

​Verification flow

Identity at initialization

JWT identification

Auto-refresh tokens

Backend token endpoint

Verification flow