> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentictrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget Identity

> Pass user identity to the widget using HMAC signatures or JWT tokens.

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:

```html theme={null}
<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>
```

<Warning>
  The `hmac` value must be computed on your backend. See [Identity Verification](/features/identity) for server-side signing examples.
</Warning>

## JWT identification

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

```javascript theme={null}
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:

```javascript theme={null}
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:

<CodeGroup>
  ```javascript Express.js theme={null}
  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 });
  });
  ```

  ```python Flask theme={null}
  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)
  ```
</CodeGroup>

## Verification flow

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