Skip to content

JWT embed verification

JWT embed verification lets you pass verified user identity from your website to the Chatevo widget — so the assistant knows who is chatting without exposing credentials in the browser.

When to use it

Scenario	Benefit
Logged-in customer portal	Personalize replies, access order history tools
Member-only areas	Block anonymous widget use on protected pages
Audit requirements	Tie conversations to known user IDs

Enable per deployment under Deployments → Web widget → Security → Require identity verification.

How it works

sequenceDiagram
  participant Your Server
  participant Browser
  participant Widget
  participant Chatevo API

  Your Server->>Browser: Page HTML + short-lived JWT
  Browser->>Widget: Chatevo.setIdentityToken(jwt)
  Widget->>Chatevo API: Message + Authorization Bearer JWT
  Chatevo API->>Chatevo API: Verify signature + claims

Your server signs a JWT with the deployment shared secret.
The page passes the token to the widget via Chatevo.setIdentityToken().
Widget API requests include Authorization: Bearer <jwt>.
Chatevo verifies signature, expiry, and required claims before processing.

JWT requirements

Claim / property	Requirement
Algorithm	`HS256` (shared secret) or `RS256` (public key uploaded)
`sub`	Stable user ID in your system
`exp`	Expiration — max 1 hour recommended
`iat`	Issued-at timestamp
`deployment_id`	Must match the widget deployment (optional but recommended)

Example payload

{
  "sub": "user_9281",
  "email": "customer@example.com",
  "name": "Jane Doe",
  "deployment_id": "dep_abc123",
  "iat": 1752652800,
  "exp": 1752656400
}

Server-side signing (Node.js example)

const jwt = require("jsonwebtoken");

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

Pass token to your page template and call Chatevo.setIdentityToken(token) after the embed script loads.

Client embed

<script
  src="https://widget.chatevo.ai/chat.js"
  data-deployment-id="dep_abc123"
  data-api-base="https://api.chatevo.ai"
  async
></script>
<script>
  window.Chatevo?.setIdentityToken("{{ server_generated_jwt }}");
</script>

Refresh the token before expiry on long-lived pages (e.g. after session refresh).

Security rules

Rule	Reason
Never expose the signing secret in client code	Anyone could forge identities
Use short `exp`	Limits replay window
Rotate secret on compromise	Invalidate all outstanding tokens
HTTPS only	Prevents token interception

When JWT is required, requests without a valid token receive 401.