Identitätsprüfung

Mit der Identitätsprüfung teilen Sie Agentkit mit, wer gerade chattet. Ihr Backend signiert ein kurzlebiges JWT für den angemeldeten Nutzer, das Widget übergibt dieses Token an Agentkit, und Agentkit verifiziert es und verknüpft die Unterhaltung mit einem Kontakt.

Es dient der Datenanreicherung und dem Schutz vor Identitätsfälschung – niemals als Zugriffssperre. Fehlt ein Token oder ist es abgelaufen oder ungültig, bedeutet das lediglich, dass der Besucher anonym chattet – der Chat wird nie blockiert.

Hinweis: Identitäts-Token enthalten private Nutzerdaten. Signieren Sie sie stets auf Ihrem Server, niemals in client-seitigem JavaScript – eine Signierung im Browser würde Ihren Signaturschlüssel offenlegen.

So funktioniert es

1. Ein Nutzer meldet sich bei Ihrer App an.
2. Ihr Backend erstellt ein kurzlebiges JWT, signiert mit dem Signaturschlüssel Ihres Agenten.
3. Sie übergeben das Token an das Widget (vor dem Laden oder zur Laufzeit).
4. Das Widget sendet das Token mit jeder Chat-Anfrage.
5. Agentkit verifiziert Signatur und Claims und erstellt oder aktualisiert anschließend einen anhand des Token-Subjects referenzierten Kontakt und verknüpft die Unterhaltung damit.

Verifizierung aktivieren

1. Öffnen Sie Ihren Agenten und gehen Sie zu Einstellungen → Identität.
2. Aktivieren Sie Angemeldete Besucher verifizieren (JWT).
3. Kopieren Sie den Signaturschlüssel.

Der Signaturschlüssel ist ausschließlich für die Serverseite bestimmt – bewahren Sie ihn in einer Umgebungsvariable auf und legen Sie ihn niemals im Client-Code offen. Das Neugenerieren des Schlüssels macht sofort alle mit dem alten Schlüssel signierten Token ungültig.

Token-Spezifikation

Signieren Sie das Token mit dem Algorithmus HS256. Andere Algorithmen (einschließlich alg: none und asymmetrischer Schlüssel) werden abgelehnt.

Claims

Nur email, name, phonenumber und custom_attributes werden aus dem Token gelesen. Jeder andere Claim der obersten Ebene wird ignoriert – zusätzliche Daten oder Integrationsdaten gehören in custom_attributes.

Limits

• email, name, phonenumber: jeweils bis zu 1024 Zeichen.
• custom_attributes: bis zu 8192 Bytes, 50 Schlüssel und 5 Verschachtelungsebenen.

Ein Token, das diese Limits überschreitet, wird als anonym verifiziert (der Fehler wird protokolliert), statt den Chat zu blockieren.

Token signieren

Jede JWT-Bibliothek funktioniert (jsonwebtoken, PyJWT, …) – Sie benötigen lediglich ein HS256-Token mit den oben genannten Claims. Dieses Beispiel verwendet jose, das auch auf Edge-Runtimes läuft (Vercel Edge, Cloudflare Workers, Deno):

// On YOUR backend, mint a short-lived JWT for your logged-in user.
import { SignJWT } from 'jose';

const secret = new TextEncoder().encode(
  process.env.AGENTKIT_CHATBOT_IDENTITY_SECRET,
);

const token = await new SignJWT({
  // Optional private profile claims — stored on the Contact, never shown to the
  // bot. ONLY these keys are read: email, name, phonenumber, custom_attributes.
  // Put extra/integration data (Stripe ids, plan, company, …) in custom_attributes.
  email: user.email,
  name: user.name,
  phonenumber: user.phone, // maps to the Contact's "phone"
  custom_attributes: {
    plan: user.plan,
    stripe_id: user.stripeCustomerId,
  },
})
  .setProtectedHeader({ alg: 'HS256' })
  .setSubject(user.id) // immutable id from YOUR system (not email/username)
  .setIssuedAt()
  .setExpirationTime('1h') // short-lived; this is a browser bearer token
  .setAudience('agentkit:chatbot:YOUR_CHATBOT_ID')
  .sign(secret);

Dasselbe Code-Snippet, bereits vorausgefüllt mit der Audience Ihres Agenten, finden Sie auf der Seite Einstellungen → Identität.

# Python example using PyJWT
import jwt, os, time

token = jwt.encode(
    {
        "sub": user.id,
        "email": user.email,
        "name": user.name,
        "phonenumber": user.phone,
        "custom_attributes": {"plan": user.plan},
        "aud": "agentkit:chatbot:YOUR_CHATBOT_ID",
        "iat": int(time.time()),
        "exp": int(time.time()) + 3600,
    },
    os.environ["AGENTKIT_CHATBOT_IDENTITY_SECRET"],
    algorithm="HS256",
)

Token an das Widget übergeben

Legen Sie das Token fest, bevor das Widget-Skript geladen wird (fügen Sie es beispielsweise serverseitig in die Seite ein):

<script>
  window.agentkitUserConfig = { token: 'YOUR_SIGNED_TOKEN' };
</script>

Aktualisieren oder löschen Sie in Single-Page-Apps die Identität zur Laufzeit – zum Beispiel nach einem Login oder Logout:

// After the user logs in (or the token is refreshed):
window.agentkit('identify', { token: newToken });

// After the user logs out:
window.agentkit('resetUser');

Das Widget hängt das Token automatisch an jede Chat-Anfrage an; Sie müssen selbst keine Header setzen.

Datenschutz

Verifizierte Profilfelder (email, name, phonenumber, custom_attributes) werden ausschließlich serverseitig im Kontakt gespeichert. Sie werden nie in den Prompt oder RAG-Kontext des Agenten eingefügt und nie von einem öffentlichen Endpunkt zurückgegeben. Der Agent „sieht" nicht, mit wem er spricht.

Verifizierungsverhalten

Die Verifizierung blockiert einen Chat nie. Der Besucher kann immer mit dem Agenten sprechen; der einzige Unterschied besteht darin, ob ein Kontakt verknüpft wird.

Andere Zugriffskontrollen gelten weiterhin

Die Identitätsprüfung ist unabhängig davon, wer das Widget laden darf. Die Einstellungen für Domain-Einschränkungen und Sichtbarkeit gelten weiterhin separat.

Nächste Schritte

• Widget mit dem Embed SDK steuern
• Kontakte verwalten
• Authentifizierung für die REST-API
• Widget bereitstellen