← Zurück zur Dokumentation

Quickstart: SaaS-Client (Beispiel SetAcademy)

Authentifizierte Nutzer aus Ihrem SaaS per Backend-zu-Backend mit SetChat verbinden, ohne Browser-CORS-Probleme.

Schritt 1 - Voraussetzungen und Variablen

Stellen Sie im SaaS-Backend eine authentifizierte Route bereit (z. B. GET /api/setchat/visitor-token), die den SetChat-S2S-Endpoint aufruft und { token, expiresIn } zurückgibt.

Minimale Backend-Variablen:

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 = Key der Ziel-Site in SetChat.
  • SETCHAT_SERVER_TOKEN = S2S-Token (in SetChat rotierbar).
  • SETCHAT_PROVIDER = stabile Kennung Ihres Produkts (z. B. setacademy).

Schritt 2 - Identitäts-Mapping und S2S-Payload

Senden Sie vom Backend ein stabiles, konsistentes Payload:

{
  "siteApiKey": "site_xxx",
  "externalUserId": "usr_123",
  "email": "user@client.com",
  "name": "Jane Doe",
  "provider": "your-saas",
  "metadata": {
    "role": "admin",
    "plan": "business",
    "tenantSlug": "acme"
  }
}
  • externalUserId muss über Sessions stabil bleiben.
  • email muss dem aktuell angemeldeten Nutzer entsprechen.
  • Keine sensiblen Daten in metadata speichern.

Schritt 3 - Widget-Integration und Session-Lifecycle

  • Bei Login oder Session-Restore Token holen und data-visitor-token im Widget setzen.
  • Bei Logout oder Account-Wechsel die Widget-Session zurücksetzen.
  • Token-Refresh einplanen, wenn App-Sessions lange laufen.

Ops-Runbook (S2S-Token-Rotation)

  1. In SetChat rotieren: POST /api/tenants/:id/widget-identity/s2s-token/rotate
  2. Ihr SaaS mit neuem Token deployen.
  3. Mint-Aufrufe prüfen (HTTP 200 + Token erhalten).
  4. Altes Token widerrufen: POST /api/tenants/:id/widget-identity/s2s-token/revoke-previous

Empfohlenes Muster: rotate → client deploy → previous revoke.