Security

Identity & User Context

Tell the agent who's talking. Sign a JWT on your backend — the widget sends it with every message.

Why identify users?

Without identity, every conversation is anonymous. With a signed JWT you get:

The agent can address the user by name and personalize responses.
Your tools receive user.sub / user.email in every call — no separate lookup needed.
Audit logs are tied to real users, not session IDs.
You can scope tool permissions per user.

Step 1 — Create a server endpoint

Add a small endpoint to your backend that signs a short-lived JWT using your Widgent Verification Secret (found in Dashboard → Settings).

Node.js / Express

// POST /api/widgent-token
import jwt from 'jsonwebtoken';

app.post('/api/widgent-token', requireAuth, (req, res) => {
  const token = jwt.sign(
    {
      sub:   req.user.id,      // required — unique user ID
      name:  req.user.name,    // optional but recommended
      email: req.user.email,   // optional but recommended
    },
    process.env.WIDGENT_SECRET,
    { expiresIn: '1h' }
  );
  res.json({ token });
});

Python / FastAPI

import jwt, os
from datetime import datetime, timedelta

@app.post("/api/widgent-token")
def widgent_token(current_user = Depends(get_current_user)):
    payload = {
        "sub":   str(current_user.id),
        "name":  current_user.name,
        "email": current_user.email,
        "exp":   datetime.utcnow() + timedelta(hours=1),
    }
    token = jwt.encode(payload, os.environ["WIDGENT_SECRET"], algorithm="HS256")
    return {"token": token}

Step 2 — Call identify() in the frontend

After your page loads and the user is authenticated, fetch the token and pass it to the widget.

// Initialize the widget first
window.widgent.init({
  productId: 'YOUR_PRODUCT_ID',
  serviceKey: 'YOUR_SERVICE_KEY',
});

// Then identify the user
const { token } = await fetch('/api/widgent-token', { method: 'POST' }).then(r => r.json());
window.widgent('identify', token);

Call identify() again whenever the user logs in or switches accounts — the widget will update immediately.

JWT schema reference

Claim	Required	Description
`sub`	✅ Yes	Unique user ID (string). Used for audit logs and scoping.
`name`	Recommended	Display name. The agent uses it to greet the user.
`email`	Recommended	User email. Available to tools as `user.email`.
`exp`	✅ Yes	Expiry timestamp. Use short-lived tokens (1h max).
`metadata`	No	Any object — passed as-is to tool handlers as `user.metadata`.

Security notes

Your Verification Secret is never sent to the browser — keep it server-side only.
Widgent verifies the token's signature on every request.
Expired tokens result in an anonymous session — the widget continues to work but loses user context.
CORS is scoped per product — only requests from your registered domain are accepted.

JS API Reference → Full reference for all window.widgent() commands. Tool Calling → Let the agent take real actions in your app.