Weryfikacja tożsamości

Weryfikacja tożsamości pozwala poinformować Agentkit, kto prowadzi rozmowę. Twój backend podpisuje krótkotrwały JWT dla zalogowanego użytkownika, widżet przekazuje ten token do Agentkit, a Agentkit weryfikuje go i łączy rozmowę z kontaktem.

To wzbogacenie danych i ochrona przed podszywaniem się, a nie brama dostępu. Brakujący, wygasły lub nieprawidłowy token oznacza po prostu, że odwiedzający rozmawia anonimowo — czat nigdy nie zostaje zablokowany.

Uwaga: tokeny tożsamości zawierają prywatne dane użytkownika. Zawsze podpisuj je na serwerze, nigdy w kodzie JavaScript po stronie klienta — podpisywanie w przeglądarce ujawniłoby Twój klucz podpisujący.

Jak to działa

1. Użytkownik loguje się do Twojej aplikacji.
2. Twój backend generuje krótkotrwały JWT, podpisany kluczem tożsamości Twojego agenta.
3. Przekazujesz token widżetowi (przed jego załadowaniem lub w trakcie działania).
4. Widżet wysyła token z każdym żądaniem czatu.
5. Agentkit weryfikuje podpis i deklaracje, a następnie tworzy lub aktualizuje kontakt na podstawie podmiotu tokenu i łączy z nim rozmowę.

Włączanie weryfikacji

1. Otwórz agenta i przejdź do Ustawienia → Tożsamość.
2. Włącz opcję Weryfikuj zalogowanych odwiedzających (JWT).
3. Skopiuj klucz podpisujący.

Klucz podpisujący działa wyłącznie po stronie serwera — przechowuj go w zmiennej środowiskowej i nigdy nie ujawniaj go w kodzie klienckim. Wygenerowanie nowego klucza natychmiast unieważnia wszystkie tokeny podpisane starym.

Specyfikacja tokenu

Podpisuj token algorytmem HS256. Inne algorytmy (w tym alg: none oraz klucze asymetryczne) są odrzucane.

Deklaracje

Z tokenu odczytywane są wyłącznie email, name, phonenumber i custom_attributes. Każda inna deklaracja najwyższego poziomu jest ignorowana — dodatkowe dane lub dane integracji umieszczaj wewnątrz custom_attributes.

Limity

• email, name, phonenumber: maksymalnie 1024 znaki każde.
• custom_attributes: maksymalnie 8192 bajty, 50 kluczy i 5 poziomów zagnieżdżenia.

Token przekraczający te limity jest weryfikowany jako anonimowy (błąd jest rejestrowany w logach), zamiast blokować czat.

Podpisywanie tokenu

Działa dowolna biblioteka JWT (jsonwebtoken, PyJWT itd.) — potrzebujesz jedynie tokenu HS256 z powyższymi deklaracjami. Ten przykład wykorzystuje bibliotekę jose, która działa również w środowiskach edge (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);

Ten sam fragment kodu, wypełniony wartością audience Twojego agenta, jest widoczny na stronie Ustawienia → Tożsamość.

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

Przekazywanie tokenu do widżetu

Ustaw token przed załadowaniem skryptu widżetu (na przykład wstrzykując go do strony po stronie serwera):

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

W aplikacjach jednostronicowych aktualizuj lub czyść tożsamość w czasie działania — na przykład po zalogowaniu lub wylogowaniu:

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

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

Widżet automatycznie dołącza token do każdego żądania czatu — nie musisz samodzielnie ustawiać żadnych nagłówków.

Prywatność

Zweryfikowane pola profilu (email, name, phonenumber, custom_attributes) są przechowywane w kontakcie wyłącznie po stronie serwera. Nigdy nie są wstrzykiwane do promptu agenta ani kontekstu RAG i nigdy nie są zwracane przez żaden publiczny endpoint. Agent nie „wie", z kim rozmawia.

Zachowanie weryfikacji

Weryfikacja nigdy nie blokuje czatu. Odwiedzający zawsze może rozmawiać z agentem — jedyna różnica dotyczy tego, czy zostaje powiązany kontakt.

Inne mechanizmy kontroli dostępu nadal obowiązują

Weryfikacja tożsamości działa niezależnie od tego, kto może załadować widżet. Ustawienia dozwolonych domen i widoczności nadal obowiązują osobno.

Kolejne kroki

• Sterowanie widżetem przez osadzone SDK
• Zarządzanie kontaktami
• Uwierzytelnianie w REST API
• Wdrażanie widżetu