Identiteitsverificatie

Met identiteitsverificatie kun je Agentkit vertellen wie er chat. Je backend ondertekent een kortlevende JWT voor de ingelogde gebruiker, de widget geeft dat token door aan Agentkit, en Agentkit verifieert het en koppelt het gesprek aan een contact.

Het is verrijking en bescherming tegen spoofing, nooit een toegangspoort. Een ontbrekend, verlopen of ongeldig token betekent simpelweg dat de bezoeker anoniem chat — de chat wordt nooit geblokkeerd.

Let op: identiteitstokens bevatten privégegevens van gebruikers. Onderteken ze altijd op je server, nooit in client-side JavaScript — ondertekenen in de browser zou je geheim blootstellen.

Hoe het werkt

1. Een gebruiker logt in bij jouw app.
2. Je backend genereert een kortlevende JWT, ondertekend met het identiteitsgeheim van je agent.
3. Je geeft het token door aan de widget (voordat deze laadt, of tijdens runtime).
4. De widget stuurt het token mee met elk chatverzoek.
5. Agentkit verifieert de handtekening en claims, en maakt of werkt vervolgens een contact bij dat gesleuteld is op het subject van het token, en koppelt het gesprek eraan.

Verificatie inschakelen

1. Open je agent en ga naar Instellingen → Identiteit.
2. Schakel Ingelogde bezoekers verifiëren (JWT) in.
3. Kopieer het ondertekeningsgeheim.

Het ondertekeningsgeheim is uitsluitend server-side — bewaar het in een omgevingsvariabele en stel het nooit bloot in client-code. Het opnieuw genereren van het geheim maakt direct elk token dat met het oude geheim is ondertekend ongeldig.

Tokenspecificatie

Onderteken het token met het HS256-algoritme. Andere algoritmes (inclusief alg: none en asymmetrische sleutels) worden geweigerd.

Claims

Alleen email, name, phonenumber en custom_attributes worden uit het token gelezen. Elke andere claim op het hoogste niveau wordt genegeerd — plaats extra of integratiegegevens binnen custom_attributes.

Limieten

• email, name, phonenumber: elk tot 1024 tekens.
• custom_attributes: tot 8192 bytes, 50 sleutels en 5 niveaus van nesting.

Een token dat deze limieten overschrijdt, wordt geverifieerd als anoniem (de fout wordt gelogd) in plaats van de chat te blokkeren.

Het token ondertekenen

Elke JWT-bibliotheek werkt (jsonwebtoken, PyJWT, …) — je hebt alleen een HS256-token nodig met de bovenstaande claims. Dit voorbeeld gebruikt jose, dat ook draait op edge-runtimes (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);

Hetzelfde fragment, vooraf ingevuld met de audience van je agent, wordt getoond op de pagina Instellingen → Identiteit.

# 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",
)

Het token doorgeven aan de widget

Stel het token in voordat het widgetscript laadt (injecteer het bijvoorbeeld server-side in de pagina):

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

Werk in single-page apps de identiteit tijdens runtime bij of wis deze — bijvoorbeeld na een login of logout:

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

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

De widget voegt het token automatisch toe aan elk chatverzoek; je hoeft zelf geen headers in te stellen.

Privacy

Geverifieerde profielvelden (email, name, phonenumber, custom_attributes) worden uitsluitend server-side opgeslagen op het contact. Ze worden nooit geïnjecteerd in de prompt of RAG-context van de agent, en nooit geretourneerd door een publiek endpoint. De agent "ziet" niet wie hij spreekt.

Verificatiegedrag

Verificatie blokkeert nooit een chat. De bezoeker kan altijd met de agent praten; het enige verschil is of er een contact wordt gekoppeld.

Andere toegangscontroles blijven van toepassing

Identiteitsverificatie staat los van wie de widget mag laden. Domeinbeperkingen en zichtbaarheid-instellingen blijven daarnaast gewoon van toepassing.

Volgende stappen

• De widget besturen met de embed-SDK
• Contacten beheren
• Authenticatie voor de REST API
• De widget inzetten