← Back to Docs

SaaS client quickstart (example: SetAcademy)

Connect authenticated users from your SaaS to SetChat with backend-to-backend calls, without browser CORS constraints.

Step 1 - Prerequisites and environment variables

On your SaaS backend, expose an authenticated route (for example GET /api/setchat/visitor-token) that calls the SetChat S2S mint endpoint and returns { token, expiresIn }.

Minimum environment variables on your backend:

SETCHAT_API_URL=https://api.setchat.co
SETCHAT_MINT_PATH=/api/widget/visitor-token
SETCHAT_SITE_API_KEY=site_xxx
SETCHAT_SERVER_TOKEN=********
SETCHAT_PROVIDER=your-saas
SETCHAT_TIMEOUT_MS=5000
  • SETCHAT_SITE_API_KEY = target SetChat site key.
  • SETCHAT_SERVER_TOKEN = S2S token (rotatable in SetChat).
  • SETCHAT_PROVIDER = stable identifier for your product (for example setacademy).

Step 2 - Identity mapping and S2S payload

Send a stable and coherent payload from your backend:

{
  "siteApiKey": "site_xxx",
  "externalUserId": "usr_123",
  "email": "user@client.com",
  "name": "Jane Doe",
  "provider": "your-saas",
  "metadata": {
    "role": "admin",
    "plan": "business",
    "tenantSlug": "acme"
  }
}
  • externalUserId must be stable across sessions.
  • email must match the currently authenticated user.
  • Avoid sensitive data in metadata.

Step 3 - Widget injection and session lifecycle

  • On login or session restore: fetch token, then inject data-visitor-token in the widget.
  • On logout or account switch: reset widget session to avoid identity leakage.
  • Refresh token if your app session can stay active for a long time.

Ops runbook (S2S token rotation)

  1. Rotate in SetChat: POST /api/tenants/:id/widget-identity/s2s-token/rotate
  2. Deploy your SaaS with the new token.
  3. Verify mint calls (HTTP 200 + token received).
  4. Revoke previous token: POST /api/tenants/:id/widget-identity/s2s-token/revoke-previous

Recommended sequence: rotate → deploy client → revoke previous.