Wenn von „Dify API Key konfigurieren“ die Rede ist, sind oft völlig verschiedene Dinge gemeint: mal der Anbieter-Schlüssel, mit dem Dify Modelle aufruft, mal der Zugangsschlüssel, mit dem ein Geschäftssystem eine Dify-Anwendung anspricht, und mal ein Service-API-Key der Wissensdatenbank. Erstellungsort, Rechteumfang und Folgen einer Offenlegung unterscheiden sich. Die häufigsten Folgen einer Vermischung: Der Anbieter-Key landet im Frontend, ein Aufrufer erhält einen zu mächtigen App-Key, oder bei der Rotation wird das falsche Objekt geändert und die Produktion meldet 401.

Oberflächennamen und RechteDetails können sich mit Versionen ändern; maßgeblich sind die aktuelle Oberfläche und Dokumentation Ihrer Instanz.

Hinweis: Dify ist eine Marke des Rechteinhabers LangGenius, Inc. Dieser Artikel ist eine unabhängige technische Darstellung; es besteht keine Zugehörigkeit oder Vertretungsbeziehung zum Dify-Team.

1. Zuerst die drei Key-Typen unterscheiden

Eine Tabelle klärt die Grenzen.

Key-Typ Zweck Erstellungsort Rechteumfang Wer verwaltet
Modellanbieter-Key Dify ruft Upstream-Modelle auf Einstellungen → Modellanbieter → jeweiliger Anbieter Im gesamten Workspace geteilt Owner, Admin
Anwendungs-API-Key Externe Systeme rufen eine Dify-Anwendung auf Anwendung → API-Zugriff Einzelne Anwendung, gilt für alle deren Endnutzer Editor und höher
Knowledge-Service-Key Externe Systeme rufen die Wissensdatenbank-API auf Wissensdatenbank → Service API Auf bestimmte Wissensdatenbanken begrenzbar Editor und höher

Die drei sind nicht austauschbar: Ein Anbieter-Key ruft keine Anwendungsschnittstelle auf, ein App-Key lässt Dify keine Modelle aufrufen. Vor der Fehlersuche zuerst feststellen, welcher Typ vorliegt.

2. Modellanbieter-Key: Workspace-Ebene, von Administratoren verwaltet

Der Modellanbieter-Key ist eine Workspace-Konfiguration. Er wird in den Einstellungen des Modellanbieters hinterlegt und von Dify für Anfragen an den Upstream verwendet. Die Plattform prüft ihn beim Hinzufügen; nach erfolgreicher Prüfung steht er dem gesamten Workspace zur Verfügung. Nur Owner und Admin verwalten ihn; Editor und Normal sehen diese Einstellungen nicht.

Einige leicht übersehene Details:

  • Ein Anbieter kann mehrere Keys speichern, getrennt nach Entwicklung, Produktion oder verschiedenen Konten, um Rechnungen zuzuordnen und einzelne Keys zu deaktivieren.
  • Keys für benutzerdefinierte Modelle werden separat verwaltet. Das Löschen des letzten Keys löscht auch das benutzerdefinierte Modell; wird nur das Modell gelöscht, bleibt der Key erhalten und muss beim erneuten Hinzufügen nicht neu eingetragen werden.
  • Professional und Team unterstützen Lastverteilung über mehrere Keys desselben Modells. Erreicht ein Key sein Limit, überspringt die Plattform ihn innerhalb einer Minute.
  • Bietet Cloud eigene AI-Credits, ist kein Anbieter-Key nötig; beides kann parallel bestehen, und Usage Priority entscheidet, welches zuerst genutzt wird. Mit eigenem Key laufen die Kosten über das eigene Anbieterkonto.

Keys nach „Zweck-Umgebung-Verantwortlicher“ benennen; die Anbieterkonsole zeigt meist den Verbrauch pro Key, was die Fehlersuche erleichtert.

3. Anwendungs-API-Key: ausschließlich im Backend

Der Anwendungs-API-Key löst ein anderes Problem: Wie ruft ein externes System eine bereits veröffentlichte Anwendung auf? Er ist nicht an der Modellauswahl beteiligt und kann nicht für Modellschnittstellen verwendet werden. Typischer Ablauf:

  1. Die Zielanwendung öffnen und die Seite API-Zugriff aufrufen.
  2. Einen Schlüssel anlegen und nach „Aufrufer-Umgebung-Datum“ benennen.
  3. In eine serverseitige Umgebungsvariable oder einen Secret-Manager kopieren, nicht in Frontend, Repository oder Chatverlauf.
  4. Zuerst GET /info aufrufen und prüfen, ob Key und Anwendung zusammenpassen.
  5. Danach die zum Anwendungstyp passende Schnittstelle aufrufen; die Typen unterscheiden sich.
  6. Nach dem Go-live Anwendung, Verantwortlichen und Erstellungszeitpunkt dokumentieren.
# Basisadresse von Dify Cloud; beim Selbstbetrieb durch die eigene Instanz ersetzen
export DIFY_BASE_URL="https://api.dify.ai/v1"
export DIFY_APP_KEY="IhrAppKey"

curl "$DIFY_BASE_URL/info" \
  -H "Authorization: Bearer $DIFY_APP_KEY"

Eine Antwort mit Anwendungsname, Modus und Beschreibung bestätigt den Key. Zwei Hinweise: Ein App-Key gilt für alle Endnutzer der Anwendung; Aufrufe unterscheiden Nutzer über das Feld user im Request-Body, aber user ist eine Kennung, keine Authentifizierung. Außerdem sollten Anwendungsschnittstellen aus dem Backend aufgerufen werden; die Dokumentation rät ausdrücklich davon ab, den Key in Frontend- oder Clientcode zu platzieren.

4. Knowledge-Service-Key: Reichweite so eng wie möglich

Die Wissensdatenbank hat einen eigenen Service-API-Key. Der Einstieg liegt auf der Seite Service API der Wissensdatenbank und ist nicht mit dem App-Key identisch. Beim Anlegen lässt sich begrenzen, auf welche Wissensdatenbanken der Key zugreifen darf; ein Key mit Zugriff auf alle Wissensdatenbanken kann zusätzlich die auflistende Schnittstelle aufrufen.

Minimale Rechte bedeuten: pro Konsument ein eigener Key, nur die benötigten Wissensdatenbanken ausgewählt, kein gemeinsamer Vollzugriffs-Key für alle Aufrufer. Ein geleakter Wissensdatenbank-Key bedeutet potenziell Lesen oder Schreiben von Daten, nicht nur verbrauchtes Modellkontingent – das Risiko ist höher.

5. Wo die Schlüssel liegen: .env, SECRET_KEY und Workspace-Verschlüsselung

Beim Selbstbetrieb gibt es zwei Ebenen; viele ändern nur die erste.

Die erste Ebene ist docker/.env, kopiert aus .env.example; Konfiguration im Wurzelverzeichnis überschreibt gleichnamige Einträge in docker/envs/*.env. Besonders SECRET_KEY wird leicht übersehen: Er ist an der Signatur von Session-Cookies und JWTs, an der HMAC-SHA256-Signatur von Datei-URLs und an der AES-256-Verschlüsselung von OAuth-Zugangsdaten Dritter beteiligt. Der Beispielwert muss ersetzt werden, etwa mit openssl rand -base64 42.

Ein Wechsel von SECRET_KEY meldet alle Nutzer ab, macht bereits ausgestellte Datei-URLs ungültig, und mit dem alten Wert verschlüsselte OAuth-Zugangsdaten sind nicht wiederherstellbar. Er gehört nicht zur regulären Rotation; vor Änderungen Auswirkungen bewerten und sichern.

Die zweite Ebene ist die Verschlüsselung der Workspace-Zugangsdaten. Modellanbieter-Keys und Tool-Zugangsdaten werden mit dem RSA-Schlüssel des jeweiligen Workspace verschlüsselt; der private Schlüssel liegt im über STORAGE_TYPE bestimmten Backend. KEY_PROVIDER_TYPE ist standardmäßig local, alternativ lässt sich Azure Key Vault mit automatischer Rotation anbinden. Diese Option muss vor dem ersten Workspace festgelegt werden: Die Chiffrate beider Verfahren sind nicht kompatibel; ein späterer Wechsel macht bestehende Zugangsdaten unlesbar, sie müssen neu eingegeben werden.

Neuere Versionen kennen in der Agent-Konfiguration außerdem DIFY_AGENT_SERVER_SECRET_KEY und DIFY_AGENT_API_TOKEN; die Entwicklungsstandardwerte sind öffentlich und müssen vor dem Go-live ersetzt werden. .env nicht ins Repository einchecken, Dateirechte nach Dokumentation beschränken und Schlüsselmaterial in die Sicherung aufnehmen, sonst sind nach einer Wiederherstellung möglicherweise alle Zugangsdaten ungültig.

Bei Cloud werden die Anbieter-Zugangsdaten von der Plattform verwaltet; SECRET_KEY muss nicht selbst gepflegt werden. Trotzdem eigene Konten oder Projekt-Keys verwenden und die Aufzeichnungen beim Anbieter behalten.

6. Rotation, minimale Rechte und Teamrollen

Rotation ist nicht nur bei Offenlegung nötig. Empfohlen bei Personalabgang, Wechsel des Aufrufers, Verdacht auf Leck, Anbieteranforderung und in festen Zyklen. Der vollständige Ablauf:

  1. Beim Anbieter oder in Dify einen neuen Key mit gleichen Rechten anlegen und zunächst parallel zum alten betreiben.
  2. Den neuen Key in den Secret-Manager oder die Umgebungsvariablen eintragen und die Konfiguration ausrollen.
  3. Eine Zeit lang Fehlerquote, Aufrufvolumen und Anbieterrechnung beobachten und bestätigen, dass der Verkehr umgestellt ist.
  4. Den alten Key deaktivieren, nicht nur aus der Konfiguration entfernen.
  5. Rotationszeitpunkt, Ausführenden und Auswirkungsbereich dokumentieren und die Übergabeunterlagen aktualisieren.

Zur Aufgabenteilung: Der Workspace-Owner hat die volle Kontrolle und existiert nur einmal; Admins verwalten Mitglieder und Modellanbieter; Editoren erstellen, bearbeiten und löschen Anwendungen und Wissensdatenbanken; Normale Mitglieder nutzen nur veröffentlichte Anwendungen. Eine einfache Regel: Anbieter-Keys bleiben bei Owner und Admin; App-Keys gehen an die verantwortlichen Backend-Teams; Wissensdatenbank-Keys werden pro Konsument getrennt und begrenzt. Editoren können Anwendungen ändern und kommen damit meist auch an deren API-Key; „Anwendung bearbeiten“ ist daher nicht gleich „unternehmensweite Modellschlüssel verwalten“.

7. Häufige Fehler und Vorgehen

Bei der Fehlersuche zuerst den Key-Typ bestätigen, dann Netzwerk und Rechte prüfen.

  • 401 Unauthorized: Key falsch geschrieben, widerrufen, mit Leerzeichen oder Zeilenumbruch versehen, oder ein Anbieter-Key wird als App-Key verwendet. Mit GET /info erneut testen.
  • 403 oder fehlende Rechte: Rolle unzureichend oder der Wissensdatenbank-Key umfasst die Zielbank nicht.
  • 404 Not Found: Base URL falsch. Cloud nutzt https://api.dify.ai/v1; beim Selbstbetrieb endet die eigene Domain auf /v1, ohne vollständigen Schnittstellenpfad.
  • Schnittstelle meldet Modell nicht verfügbar: Anbieter-Key abgelaufen, Guthaben aufgebraucht oder Upstream-Rate-Limit; in den Modellanbieter-Einstellungen neu prüfen.
  • Wissensdatenbank-Schnittstelle 404/403: App-Key und Service-Key verwechselt oder die Wissensdatenbank liegt außerhalb des Key-Bereichs.
  • 429 Too Many Requests: Rate-Limit erreicht. Parallelität senken und mit exponentiellem Backoff wiederholen.
  • Nach Wechsel des SECRET_KEY sind alle abgemeldet: Erwartetes Verhalten, siehe vorheriger Abschnitt; zuerst Auswirkungen bewerten und nicht direkt zum alten Wert zurückkehren.

Ein weiterer häufiger Irrtum: Dify läuft im Container oder in der Cloud, es wird aber localhost oder eine interne Adresse eingetragen. Dify erreicht den lokalen Dienst nicht; auch ein korrekter Key hilft dann nicht. Wenn ein Geschäftssystem die selbst betriebene Dify-Instanz nicht erreicht, zuerst DNS, Firewall, Reverse Proxy und Zertifikate prüfen.

Häufige Fragen

Lassen sich Modellanbieter-Key und Anwendungs-API-Key austauschen?

Nein. Ersterer dient Dify für Aufrufe der Upstream-Modelle, letzterer externen Systemen für Aufrufe der Dify-Anwendung. Schnittstellen, Rechte und Abrechnungsobjekt sind unterschiedlich.

Kann eine Anwendung mehrere API-Keys haben?

Üblicherweise ja. Verbreitet ist die Aufteilung nach Umgebung oder Aufrufer, um einzelne Keys deaktivieren und nachverfolgen zu können. Der genaue Einstieg richtet sich nach der aktuellen Oberfläche.

Lässt sich ein Anwendungs-API-Key auf eine Wissensdatenbank oder einen Nutzer begrenzen?

Der App-Key gilt auf Anwendungsebene und lässt sich nicht nach Wissensdatenbank aufteilen; das Feld user unterscheidet Endnutzer, ist aber kein Authentifizierungsmechanismus. Für Wissensdatenbank-Rechte den Service-API-Key mit passender Auswahl verwenden.

Beeinflusst ein Wechsel des SECRET_KEY die Modellanbieter-Keys?

Anbieter- und Tool-Zugangsdaten werden mit dem RSA-Schlüssel des Workspace verschlüsselt, nicht direkt mit SECRET_KEY; nach einem Wechsel werden Nutzer abgemeldet, Datei-URLs ungültig und OAuth-Zugangsdaten unlesbar. Vor Änderungen in der Produktion die Deployment-Dokumentation lesen und sichern.

Nach einem Selbstbetrieb-Upgrade sind Keys plötzlich ungültig – was zuerst prüfen?

Zuerst .env.example mit der vorhandenen .env auf neue Variablen vergleichen, dann bestätigen, dass KEY_PROVIDER_TYPE und das Speicher-Backend unverändert sind; wurde die Verschlüsselungsart gewechselt, sind alte Zugangsdaten nicht entschlüsselbar und müssen neu eingegeben werden. Zuletzt die Fehlercodes im Anwendungslog prüfen.

Nächste Schritte

Die Key-Verwaltung in Dify lässt sich in drei Sätzen zusammenfassen: zuerst den Typ unterscheiden, dann nach minimalen Rechten ausgeben und die Rotation als festen Prozess behandeln. Für einen einheitlichen OpenAI-kompatiblen Zugang und zentral verwaltete Modellaufrufe können Sie sich im ZSQH AI Gateway registrieren; Modellumfang und Preise entnehmen Sie den Modellpreisen.

Weiterlesen: