Authentifizierung

Der App-Ersteller legt den Authentifizierungstyp einer Verbindung fest, der Installierer im AI Agent nutz bei Installation seine eigenen Zugangsdaten.

Wo finde ich das?

Die Authentifizierung gehört zur Verbindung einer App und wird an zwei Stellen bearbeitet:

• Im Workspace unter Apps → ‹App› → Verbindungen: Hier legst du fest, welche Authentifizierung gilt, sowie bei OAuth2 die Client-Konfiguration.

• Im AI Agent unter Einstellungen → App Store → ‹App›: Hier trägt der Installierer seine eigenen Zugangsdaten ein.

---

Erklärung – Zwei Rollen, zwei Orte

Authentifizierung ist nicht Teil des Request-JSON, sondern eine Ebene darüber.

Rolle	Legt fest	Wo
App-Ersteller	Den Auth-Typ der Verbindung und, bei OAuth2, die Client-Konfiguration der App.	Workspace → Apps
App-Installierer	Die konkreten Zugangsdaten – Benutzername, Token oder den Login beim externen Anbieter.	AI Agent → App Store

Zugangsdaten gehören zur Installation, nicht zur App. Installieren zwei AI Agents dieselbe App, hat jeder seine eigenen Zugangsdaten.

---

Die Authentifizierungstypen

Den Typ wählst du beim Anlegen der Verbindung im Feld Typ:

Typ	Wer trägt was ein	Authorization-Header
Keine Authentifizierung	niemand	–
Basic Auth	Installierer: Benutzername und Passwort	automatisch
Bearer Token	Installierer: Token	automatisch
OAuth2 Authorization Code	Ersteller: Client-Konfiguration Installierer: Login beim Anbieter	automatisch
Benutzerdefinierte Authentifizierung	Installierer: Parameter	selbst schreiben

---

Der Header und die Platzhalter

Bei Basic Auth, Bearer Token und OAuth2 setzt die Plattform den Authorization-Header selbst – in der Healthcheck-Abfrage der Verbindung und in jedem Modul, das sie nutzt. Schreibst du den Header selbst ins JSON, gilt weiter deiner.

Brauchst du die Werte an anderer Stelle im Body, in einem Query-Parameter oder in einem abweichenden Header, stehen sie als Platzhalter bereit:

Typ	Platzhalter
Basic Auth	{{auth.username}}, {{auth.password}}, {{auth.token}}
Bearer Token	{{auth.token}}
OAuth2 Authorization Code	{{auth.accessToken}}

Der Editor listet die verfügbaren Platzhalter jeweils über dem Eingabefeld auf. Ein Name, der nicht in dieser Liste steht, wird nicht ersetzt und bleibt als Text im Request stehen.

---

Installationsabhängige Werte im OAuth2-Flow

Manche Anbieter brauchen einen Wert, der je Installation anders ist, bevor der Login überhaupt starten kann; etwa den Shop-Namen bei Shopify, eine Tenant-ID oder eine Region. Dieser Wert steht in der Authorize-URL und kann vom Ersteller nicht immer fest mitgegeben werden.

Nutze dafür die normalen Parameter der Verbindung aus dem Tab Parameter. In allen drei OAuth2-Editoren steht {{parameters.[NAME]}} als Platzhalter zur Verfügung und wird durch den Wert ersetzt, den der Installierer eingetragen hat:

{
  "url": "https://{{parameters.shop}}.myshopify.com/admin/oauth/authorize",
  "params": {
    "client_id": "{{auth.clientId}}",
    "redirect_uri": "{{auth.redirectUri}}",
    "response_type": "code",
    "state": "{{auth.state}}",
    "scope": "read_products"
  }
}

Der Ersatz greift in allen drei Stufen: Autorisierung, Token-Tausch und Erneuerung, sodass derselbe Wert auch später noch zur Verfügung steht.

Ein Parameter, den du als required definierst, muss gefüllt sein: Fehlt der Wert, bricht der Verbindungsversuch ab. Ein optionaler Parameter ohne Wert wird durch eine leere Zeichenkette ersetzt – was in einer URL meist zu einem Fehler beim Anbieter führt. Die Basisdaten der App ({{baseUrl}}) werden in den OAuth2-Editoren nicht aufgelöst, dort gelten nur {{auth.*}} und {{parameters.*}}.

---

Verwaltung – OAuth2 Authorization Code vorbereiten

Diese Schritte macht der App-Ersteller einmal. Der Tab OAuth2-Konfiguration erscheint nur bei Verbindungen dieses Typs.

1

Redirect URI beim Anbieter hinterlegen

Öffne Verbindungen → ‹Verbindung› → OAuth2-Konfiguration. Hier findest du die Redirect URI. Kopiere sie über das Kopieren-Symbol und hinterlege sie beim Anbieter als erlaubte Weiterleitungs-URL.

2

Client ID und Client Secret eintragen

Beides erhältst du vom Anbieter. Das Secret wird nach dem Speichern nicht mehr angezeigt – das Feld meldet dann Ein Secret ist gespeichert. Feld leer lassen, um es beizubehalten. Ein leeres Feld behält das zuvor gespeicherte Secret.

3

PKCE aktivieren, wenn der Anbieter es unterstützt

Der Schalter PKCE aktivieren (Proof Key for Code Exchange) sichert den Austausch zusätzlich ab. {{auth.codeChallenge}} und {{auth.codeVerifier}} werden dann automatisch erzeugt und stehen in den Editoren zur Verfügung.

4

Authorize Request anpassen

Das Feld ist mit einer Vorlage vorbelegt, die auf example.com zeigt. Ersetze die URL durch die Authorize-Adresse des Anbieters. Es gibt kein eigenes Feld für Scopes: Trage den Scope als Parameter in params ein.

access_type und prompt sind bewusst vorbelegt. Manche Anbieter liefern nur mit ihnen ein Refresh-Token, ohne welches die Verbindung nach etwa einer Stunde enden würde. Anbieter, die die Parameter nicht kennen, ignorieren sie.

5

Token Request anpassen

Auch hier zeigt die Vorlage auf example.com. Ersetze die URL durch die Token-Adresse des Anbieters und prüfe, ob Methode, Header und Body zu dessen Dokumentation passen.

6

Refresh Request nur bei Bedarf

Die Erneuerung läuft automatisch im Hintergrund. Einen eigenen Refresh Request brauchst du nur, wenn der Anbieter ein abweichendes Format erwartet. Dann schaltest du Eigenen Refresh Request verwenden ein.

7

Speichern

Bestätige unten mit Speichern. Danach kann die App installiert und die Verbindung autorisiert werden.

---

Verwaltung – Zugangsdaten eintragen

Diese Schritte macht der Installierer im AI Agent, nach dem Installieren der App.

1

Verbindung öffnen

Öffne die App unter Einstellungen → App Store und klicke im Warnhinweis auf Einrichten oder auf das Stift-Symbol neben der Verbindung. Der Dialog nennt oben den Namen der Verbindung, ihren Auth-Typ und den Status Verbunden oder Nicht verbunden.

2

Zugangsdaten hinterlegen

Je Typ sind andere Felder zu füllen: bei Basic Auth Benutzername und Passwort, bei Bearer Token das Feld Token. Ein bereits gespeicherter Wert wird nicht mehr angezeigt; lässt du das Feld leer, bleibt er erhalten.

3

Parameter ausfüllen

Sieht die App Parameter vor, stehen sie darunter. Bei OAuth2 gehören sie vor den Login: Sie werden gespeichert, bevor sich das Fenster des Anbieters öffnet, und können Teil der Authorize-URL sein. Solange ein Pflichtfeld leer ist, bleibt die Schaltfläche inaktiv.

4

Bei OAuth2: Zugriff autorisieren

Klicke auf Verbinden. Es öffnet sich ein Popup-Fenster mit dem Login des Anbieters. Melde dich dort an und stimme dem Zugriff zu. Erscheint kein Fenster, blockiert der Browser Popups für diese Seite – erlaube sie und versuche es erneut.

5

Bestätigen

Schließe mit Verbinden ab. Die Plattform führt die Healthcheck-Abfrage der Verbindung gegen die echte API aus; erst wenn diese gelingt, steht die Verbindung auf Verbunden und die Module sind einsatzbereit.

Bei einer bereits eingerichteten Verbindung heißt der Dialog Verbindung bearbeiten, und die Schaltfläche heißt Speichern beziehungsweise bei OAuth2 Erneut verbinden.

---

Tokens und ihre Erneuerung

Ein Zugriffstoken aus einem OAuth2-Login ist meist etwa eine Stunde gültig. Damit die Verbindung dennoch dauerhaft hält, erneuert die Plattform das Token selbst:

• Vorausschauend, fünf Minuten vor Ablauf. Scheitert das, folgen bis zu drei Versuche mit wachsendem Abstand.

• Sofort, wenn die API einen Modulaufruf mit 401 oder 403 ablehnt. Das Token wird erneuert und der Aufruf einmal wiederholt.

Wie lange ein Token gültig ist, entnimmt die Plattform der Antwort des Anbieters. Nennt er keine Laufzeit, gilt das Token als dauerhaft gültig und es wird keine Erneuerung eingeplant.

Scheitern alle Versuche, wird die Verbindung auf Nicht verbunden gesetzt. Auf der App-Detailseite erscheint dann der Hinweis Verbindung gescheitert mit dem Zeitpunkt des Ausfalls und der Schaltfläche Neu verbinden.

Ohne Refresh-Token kann nichts erneuert werden – die Verbindung endet dann mit dem ersten Ablauf des Tokens. Liefert ein Anbieter kein Refresh-Token, obwohl er es unterstützt, fehlen im Authorize Request meist die Parameter für den Offline-Zugriff. Überwache deshalb den ersten Refresh-Zyklus.

---

Wenn eine Verbindung nicht zustande kommt

Schlägt eine Autorisierung fehl, nennt der Dialog den Grund:

Meldung	Was zu tun ist
Die Autorisierung wurde abgebrochen.	Der Zugriff wurde im Fenster des Anbieters abgelehnt. Erneut versuchen und zustimmen.
Der externe Dienst hat die Autorisierung abgelehnt.	Berechtigungen beim Anbieter prüfen. Häufig fehlt dem Konto die Freigabe.
Die Autorisierung ist abgelaufen.	Zwischen Öffnen und Abschluss lag zu viel Zeit. Vorgang neu starten.
Der Zugriffstoken konnte nicht abgerufen werden.	Client ID, Client Secret und den Token Request der App prüfen.
Die Autorisierung war erfolgreich, aber die Healthcheck-Abfrage … ist fehlgeschlagen.	Der Login hat geklappt, die Test-Abfrage nicht. Endpunkt und Berechtigungen der Healthcheck-Abfrage prüfen.
Die OAuth2-Konfiguration dieser Verbindung ist unvollständig oder ungültig.	Die Angaben in der App fehlen oder passen nicht zusammen – Aufgabe des App-Erstellers.
Der Vorgang wurde nicht abgeschlossen.	Es kam keine Antwort zurück. Meist stimmt die Redirect URI beim Anbieter nicht, oder Client ID beziehungsweise Scopes sind falsch.
Der Zugriff ist abgelaufen und konnte nicht automatisch erneuert werden.	Erneut autorisieren über Neu verbinden.

---

Best Practices

• Erst der Anbieter, dann die App: Hinterlege die Redirect URI beim Anbieter, bevor du testest. Sie ist die häufigste Ursache für einen Login, der ohne Rückmeldung endet.

• Vorlagen wirklich ersetzen: Authorize- und Token-Request sind mit example.com vorbelegt. Eine vergessene Vorlage fällt erst beim ersten Verbindungsversuch auf.

• Installationsabhängiges als Parameter anlegen: Alles, was je Installation anders ist, gehört in die Parameter der Verbindung. Nicht fest in die Authorize-URL. Sonst lässt sich die App nur ein einziges Mal sinnvoll installieren.

• Healthcheck-Abfrage passend wählen: Sie entscheidet, ob eine Autorisierung als erfolgreich gilt. Nimm einen Endpunkt, der ohne gültiges Token fehlschlägt. Ein Endpunkt, der immer antwortet, verbirgt einen kaputten Header.

• Sprechende Namen für Verbindungen: Im Einrichtungsdialog des Installierers ist der Name die einzige Orientierung, welche Zugangsdaten gemeint sind.