Server-to-Server-Einbettung

Standardmäßig spricht das Widget die AI-Hub-API direkt aus dem Browser an und authentifiziert sich dabei mit einem öffentlichen API-Schlüssel. Für viele Anwendungsfälle reicht das aus.

In manchen Szenarien soll die Chat-Komponente aber in eine eigene Applikation eingebettet werden, in der

• ein persistenter, personalisierter Chat-Verlauf pro angemeldetem Benutzer geführt wird und
• die Benutzeridentität serverseitig aus der eigenen Anwendung stammt und nicht manipulierbar sein darf.

Persistenter Verlauf pro Benutzer erfordert einen geheimen API-Schlüssel — und ein geheimer Schlüssel darf niemals im Browser sichtbar sein.

Die Lösung: Das Widget schickt seine Requests nicht mehr direkt an den AI Hub, sondern an ein eigenes Backend. Dieses ergänzt den geheimen Schlüssel und die geprüfte Benutzer-ID und leitet den Request dann an den AI Hub weiter (ein solcher Vermittler wird auch Proxy genannt). Der geheime Schlüssel bleibt so ausschließlich auf dem eigenen Server.

Damit das Widget statt des AI Hubs Ihr Backend anspricht, lässt sich mit dem Attribut api-url der API-Endpunkt des Widgets überschreiben.

info

Die überschreibbare API-URL ist ausschließlich für die Einbettung in externe Applikationen gedacht.

Ablauf

Browser (<ai-hub-chat api-url="…">)
        │  Request an Ihr Backend (ohne Schlüssel)
        ▼
Ihr eigenes Backend
        │  fügt geheimen Schlüssel + geprüfte Benutzer-ID hinzu
        ▼
AI Hub API

Schritt 1: Geheimen Schlüssel erstellen

Im Bereich API Keys einen API-Schlüssel vom Typ Widget erstellen und Geheim wählen. Der Schlüssel muss sicher im eigenen Backend aufbewahrt werden — er wird nur einmalig angezeigt und darf nicht im Frontend landen.

Schritt 2: Weiterleitung im eigenen Backend einrichten

Das eigene Backend stellt einen Endpunkt (z. B. https://ihre-app.example.com/ai-proxy) bereit, der die Requests des Widgets entgegennimmt und weiterleitet. Für jeden weitergeleiteten Request muss das Backend:

1. Den Benutzer in der eigenen Anwendung authentifizieren.
2. Den Header X-Api-Key mit dem geheimen Schlüssel setzen.
3. Die userId durch die tatsächliche, geprüfte Benutzer-ID ersetzen (im Request-Body bzw. als Query-Parameter). Die vom Widget übergebene user-id gilt nur als Hinweis und darf nicht ungeprüft übernommen werden.
4. Den Request an die AI Hub API weiterleiten.

Dabei muss keine feste Liste von Endpunkten gepflegt werden: Das Backend leitet jeden eingehenden Request generisch weiter — mit Methode, Query-Parametern und Body unverändert. Es stellt lediglich den Pfad-Präfix wieder her, den das Widget weglässt:

Request an api-url beginnt mit …	Weiterleiten an
/chat, /custom-file-uploads, /speech	<AI_HUB_API>/api/v1<pfad>
/file-uploads	<AI_HUB_API>/api<pfad>

Damit sind automatisch alle Endpunkte abgedeckt, die das Widget nutzt (Chat, Verlauf, Feedback, Datei-Upload, Sprache und Datei-Downloads). Welche Endpunkte das im Einzelnen sind und welche Parameter sie erwarten, ist in der Swagger/OpenAPI-Collection dokumentiert — das Backend muss diese Requests nur unverändert durchreichen.

warnung

Auch Bild- und Datei-Downloads laufen über das eigene Backend. Es muss diese GET-Requests ebenfalls weiterleiten, sonst werden hochgeladene Dateien und Bilder im Chat nicht angezeigt.

Schritt 3: Widget einbetten

Das Widget mit api-url (statt api-key) einbetten und die Benutzer-ID über user-id mitgeben:

<ai-hub-chat
    language="de"
    height="690"
    width="570"
    integration-location="#IHR_STANDORT"
    api-url="https://ihre-app.example.com/ai-proxy"
    user-id="[BENUTZER_ID]"
    widget-id="[WIDGET_ID]"
/>
<script src="[SCRIPT_URL]" type="module" defer></script>

Da kein Schlüssel im Browser liegt, wird api-key weggelassen — die Authentifizierung übernimmt vollständig das eigene Backend.

Attribute

Attribut	Erforderlich	Beschreibung
api-url	Ja	Basis-URL des eigenen Backend-Endpunkts. Ist sie gesetzt, sendet das Widget keinen api-key und ruft alle Endpunkte relativ zu dieser URL auf. Erlaubt sind absolute URLs (https://…) und Same-Origin-Pfade (/ai-proxy).
user-id	Nein	Kennung des angemeldeten Benutzers als Hinweis. Die verbindliche, geprüfte userId setzt das Backend.
widget-id	Ja	Die ID des Widgets.

Die übrigen Attribute (language, height, width, integration-location) verhalten sich wie bei der normalen Widget-Einbettung.