← Back to Docs

Verified visitor identity

Reliably map authenticated SaaS users to SetChat conversations with a backend-signed token.

Recommended architecture

  1. Your backend validates authenticated user.
  2. Your backend requests a signed visitor token (S2S).
  3. Your frontend injects token into SetChat widget.
  4. On logout/user switch, reset widget session.

Recommended payload

{
  "siteApiKey": "site_xxx",
  "externalUserId": "usr_123",
  "email": "user@client.com",
  "name": "Jane Doe",
  "provider": "setacademy",
  "metadata": { "role": "admin", "plan": "business" }
}

SetChat API contract (S2S)

Endpoint: POST /api/widget/visitor-token

Auth: Authorization: Bearer <SETCHAT_SERVER_TOKEN>

Body: siteApiKey, externalUserId, email, name, provider, metadata

Response: { token, expiresIn, expires_in }

Quick test (copy/paste cURL)

In 30 seconds, test S2S minting from your terminal with your own variables. 

SETCHAT_API_URL=https://api.setchat.co
SETCHAT_SERVER_TOKEN=replace_with_server_token
SETCHAT_SITE_API_KEY=site_xxx

curl -X POST "$SETCHAT_API_URL/api/widget/visitor-token" \
  -H "Authorization: Bearer $SETCHAT_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"siteApiKey\": \"$SETCHAT_SITE_API_KEY\",
    \"externalUserId\": \"usr_demo_123\",
    \"email\": \"demo@example.com\",
    \"name\": \"Demo User\",
    \"provider\": \"setacademy\",
    \"metadata\": {\"role\": \"admin\"}
  }"

Expected response (example):

{
  "token": "eyJhbGciOi...",
  "expiresIn": 300,
  "expires_in": 300,
  "expiresInLabel": "5m"
}

If you get 401 or 400, see the troubleshooting page.

Rotation and revocation (ops)

  • Rotate S2S token: POST /api/tenants/:id/widget-identity/s2s-token/rotate
  • Revoke previous tokens: POST /api/tenants/:id/widget-identity/s2s-token/revoke-previous
  • Recommended sequence: rotate - deploy client - revoke previous.
  • The rotated token is shown once only.