# Schützen Sie einen Assistenten mit Ihrer eigenen Anmeldung über callbackUrl

`callbackUrl` ist das Feld, das Sie verwenden, wenn ein coreAI-Assistent nur für angemeldete Nutzer in Ihrem eigenen System verfügbar sein soll. Ist das Feld gesetzt, kontaktiert coreAI Ihre eigene URL mit dem Token des Nutzers, bevor das Chat-Widget initialisiert wird, und nur Nutzer, die Ihr Endpoint per HTTP 200 freigibt, dürfen mit dem Assistenten sprechen. Anmeldung, Sitzung und Nutzerdatenbank bleiben bei Ihnen – coreAI verwaltet nicht, wer wer ist.

## Wann Sie callbackUrl einsetzen sollten

Verwenden Sie `callbackUrl`, wenn der Assistent auf Daten antwortet, die nicht öffentlich sein dürfen: Kundenportale, Intranets, Mitarbeiterdokumente oder Mehrkundenlösungen, in denen jeder Nutzer nur seine eigenen Daten sehen soll. Das typische Setup: Der Nutzer meldet sich bei Ihnen an, Sie betten das coreAI-Widget auf einer geschützten Seite ein, und das Widget übermittelt ein Token (Ihre eigene Session-ID, ein JWT, ein signierter Einmalcode – was Sie ohnehin schon nutzen), das coreAI gegen Ihren Endpoint prüft, bevor der Chat startet.

Soll der Assistent allen Besuchern einer offenen Seite antworten, brauchen Sie keine `callbackUrl`. Lassen Sie das Feld leer.

## Zwei Wege, das Token zu übermitteln

`callbackUrl` unterstützt zwei Formate, und coreAI wählt die Methode anhand der URL-Schreibweise:

- **`{TOKEN}` in der URL.** Schreiben Sie `https://mein-system.de/validate?token={TOKEN}`, dann ersetzt coreAI den Platzhalter durch das Nutzer-Token und ruft die URL per GET auf (Fallback auf POST, wenn GET 404 liefert). Der Platzhalter darf an beliebiger Stelle der URL stehen, auch im Pfad: `https://mein-system.de/validate/{TOKEN}` funktioniert ebenso.
- **Bearer-Header.** Schreiben Sie eine feste URL ohne `{TOKEN}`, etwa `https://mein-system.de/api/validate`. coreAI ruft die URL dann per POST auf und ergänzt `Authorization: Bearer <token>` (Fallback auf GET, wenn POST 404 liefert).

Wählen Sie, was sich am einfachsten in Ihren bestehenden Auth-Stack integrieren lässt. Die Bearer-Variante passt am besten, wenn Sie bereits eine JSON-API zur Token-Validierung haben; die URL-Variante ist am einfachsten, wenn der Validator ein eigenständiger Endpoint ist.

## So antwortet Ihr Endpoint

Ihr Endpoint muss HTTP 200 mit einem JSON-Body liefern, damit der Nutzer durchgelassen wird. Alles andere – 401, 403, 500, Netzwerkfehler – wird als Ablehnung gewertet, und das Widget wird nicht initialisiert. Enthält die Antwort das Feld `status`, muss der Wert `"success"` sein; alles andere lehnt ab, selbst wenn der Statuscode 200 ist.

Die JSON-Antwort kann zudem eine oder mehrere `external_id`-Werte zurückgeben:

```json
{
  "status": "success",
  "external_id": ["customer-4711", "department-sales"]
}
```

Ist das Feld vorhanden, sperrt coreAI die Konversation auf die Datenquellen, die diesen `external_id`-Werten in der Wissensdatenbank des Assistenten entsprechen. Genau dieser Mechanismus macht Mehrkundenportale praktikabel: ein Assistent, eine Wissensdatenbank, aber jeder Nutzer sieht nur seine eigenen Bestellungen, die Dokumente seiner Organisation, seine eigenen Inhalte. Sie bestimmen das Scoping in Ihrem eigenen Endpoint – coreAI liest nur das Ergebnis.

## Was automatisch deaktiviert wird

Sobald ein Assistent eine `callbackUrl` gesetzt hat, deaktiviert coreAI drei Oberflächen, die die Prüfung andernfalls umgehen würden:

- **Öffentliche Such-Demo** – der Such-Endpoint für unveröffentlichte Demo-Treffer antwortet mit 403.
- **Direktlink zum Widget** – die teilbare URL, die das Widget allein im Browser öffnet, liefert 403.
- **MCP-Exposition** – der Assistent wird nicht als MCP-Tool für KI-Agenten registriert.

An der Callback führt kein Weg vorbei, sobald sie gesetzt ist. Wollen Sie wieder etwas öffentlich anbieten, müssen Sie `callbackUrl` entfernen oder einen separaten Assistenten für die offene Oberfläche anlegen.

## Warum die Prüfung einmal pro Widget-Ladevorgang läuft

Das Token wird beim Initialisieren des Widgets validiert – also einmal pro Seitenaufruf – und nicht für jede Frage des Nutzers oder jede gestreamte Antwort. Das ist eine bewusste Entscheidung. Eine erneute Validierung bei jedem Chat-Aufruf würde zwischen jeder Frage und jeder Antwort die Netzwerklatenz Ihres Endpoints einfügen, ohne realen Sicherheitsgewinn: Der Zugriff auf den Assistenten ergibt sich bereits daraus, dass das Widget in einer authentifizierten Sitzung geladen wurde. Eine kompromittierte Sitzung bei Ihnen käme durch, egal wie oft coreAI nachfragen würde.

In der Praxis heißt das: Ihr Endpoint erhält eine HTTP-Anfrage pro geöffneter Seite, auf der der Assistent eingebunden ist. Das ist eine realistische Last, auch für Endpoints, die schwere Lookups gegen Ihre Datenbank ausführen.