In n8n heißen mindestens drei Dinge „Key“: der öffentliche API-Key zur Verwaltung der n8n-Instanz, der OpenAI-kompatible Key für Modellaufrufe und der N8N_ENCRYPTION_KEY, der Zugangsdaten in der Datenbank schützt. Die drei haben unterschiedliche Zwecke; wer sie verwechselt oder falsch ablegt, erzeugt Sicherheitsprobleme. Viele Anfragen nach „Konfiguration wirkt nicht“ beruhen darauf, dass eine Art für eine andere gehalten wurde.

Dieser Artikel folgt der Reihenfolge „Was ist es, wo gehört es hin, wie wird rotiert, wie wird bei Problemen gesucht“ und richtet sich an selbst betriebene Teams sowie Instanzen mit mehreren Nutzern.

Hinweis: n8n ist eine Marke von n8n GmbH, OpenAI ist eine Marke von OpenAI, Inc. Dieser Artikel dient der technischen Erläuterung; es besteht keine Zugehörigkeits- oder Kooperationsbeziehung zu den genannten Unternehmen. Preise und verfügbare Modelle entnehmen Sie den Modellpreisen.

1. Drei Key-Arten unterscheiden

Typ Zweck Ablageort Typischer Request-Header
n8n Public API Key Aufruf der REST-API von n8n, Verwaltung von Workflows und Ausführungen In der n8n-Oberfläche erstellt, beim Aufrufer gespeichert X-N8N-API-KEY
Modellservice-Key Aufruf OpenAI-kompatibler Schnittstellen n8n-Zugangsdaten, verschlüsselt in der Datenbank Authorization: Bearer ...
N8N_ENCRYPTION_KEY Verschlüsselung der Zugangsdaten in der Datenbank Umgebungsvariable oder .n8n-Konfigurationsdatei Wird nicht als Header gesendet

Ein Public-API-Key darf nicht für Modellaufrufe verwendet werden, ein Modell-Key nicht für die Verwaltung von n8n-Workflows. Die unmittelbare Folge sind 401 oder ungewollt erweiterte Rechte.

2. n8n Public API Key erstellen

Der Einstieg liegt unter Settings > n8n API; dort „Create an API key“ wählen und Label sowie Ablaufzeit eintragen. Laut offizieller Dokumentation ist die Public API in der kostenlosen Cloud-Testphase nicht verfügbar; die Enterprise-Version erlaubt Scopes, um den Key auf konkrete Ressourcen und Aktionen wie workflow:read oder credential:list zu begrenzen. Keys ohne Enterprise beschränken die Rechte nicht automatisch, daher muss der Kreis der Inhaber kontrolliert werden.

Beim Aufruf steht der Key im Header X-N8N-API-KEY, der Pfad ist üblicherweise /api/v1:

curl -sS "https://deine-n8n-domain/api/v1/workflows?active=true" \
  -H "accept: application/json" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Einige Regeln:

  1. Ein Key dient genau einem Zweck, etwa CI, Monitoring oder internen Tools.
  2. Ablaufzeit setzen und vor Ablauf aktiv rotieren.
  3. Den Key nicht in Frontend-Code, URL-Parameter oder Logs schreiben.
  4. Public-API-Keys nicht als Modell-Keys verwenden.
  5. Bei Bedarf die Public API mit N8N_PUBLIC_API_DISABLED=true abschalten.

3. Modell-Zugangsdaten: Der Key gehört in die Credentials

Für OpenAI-kompatible Dienste eine Zugangsdatenart „OpenAI“ verwenden und API Key sowie Base URL eintragen. Die Gateway-Adresse endet üblicherweise auf /v1, etwa https://ai.zhongshangqihang.com/v1. Die Organization ID ist nur bei offiziellen OpenAI-Konten mit mehreren Organisationen nötig und bleibt bei einem kompatiblen Gateway meist leer. Zugangsdaten unterstützen zusätzliche benutzerdefinierte Header, falls das Gateway weitere Kennungen verlangt.

Der Key darf an folgenden Stellen nicht auftauchen:

  • in Code-, Set- oder Prompt-Nodes;
  • in normalen Feldern des Workflow-JSON;
  • in Webhook-Antworten, Ausführungslogs oder Fehlerbenachrichtigungen;
  • in Screenshots, Bildschirmaufnahmen oder freigegebenen Dokumenten.

Workflow-Exporte enthalten die Zugangsdaten selbst meist nicht, aber in Node-Parametern eingetragene Keys gelangen mit dem JSON nach außen. Durchsuchen Sie Workflows vor der Freigabe nach sk- und gängigen Key-Präfixen.

4. Umgebungsvariablen: Konfiguration ja, Secret-Speicher nein

Selbst betriebenes n8n konfiguriert Port, Datenbank und Webhook-Adresse über Umgebungsvariablen. Auch sensible Werte wie N8N_ENCRYPTION_KEY und Datenbankpasswörter sollten über Umgebungsvariablen oder einen Secret-Manager injiziert werden, nicht in einer Compose-Datei in Git landen. Einige Variablen unterstützen das Suffix _FILE, um den Wert aus einer separaten Datei zu lesen.

Umgebungsvariablen sind jedoch kein sicherer Secret-Speicher. Die n8n-Dokumentation weist ausdrücklich darauf hin, dass Umgebungsvariablen in n8n nicht geschützt sind und für Nutzer sichtbar werden können; die massenhafte Verteilung von Zugangsdaten über CREDENTIALS_OVERWRITE_DATA ist daher nicht empfehlenswert. Sicherer ist ein authentifizierter Overwrite-Endpoint.

Dürfen Fachanwender Workflows bearbeiten, sollte N8N_BLOCK_ENV_ACCESS_IN_NODE=true aktiviert werden, damit Ausdrücke und Code-Nodes keine Umgebungsvariablen lesen. Der Standardwert ist false; nach der Änderung ist ein Neustart nötig. Außerdem speichert der Ausführungsverlauf Ein- und Ausgaben von Nodes; sensible Felder sollten vor dem Eintritt in n8n maskiert oder die Aufbewahrung über EXECUTIONS_DATA_MAX_AGE verkürzt werden.

5. Verschlüsselungsschlüssel: Bei Verlust sind alle Zugangsdaten unlesbar

Beim ersten Start erzeugt n8n automatisch einen Verschlüsselungsschlüssel im Verzeichnis ~/.n8n und verschlüsselt damit die in die Datenbank geschriebenen Zugangsdaten. Alternativ lässt sich über N8N_ENCRYPTION_KEY ein eigener Wert vorgeben. Laut offizieller Dokumentation sind bei Verlust dieses Schlüssels alle gespeicherten Zugangsdaten nicht mehr lesbar.

Backups müssen daher paarweise erfolgen: Datenbankbackup und Verschlüsselungsschlüssel getrennt speichern und getrennt zugreifen. Nur die Datenbank zu sichern hilft nicht, weil nach der Wiederherstellung der Originalschlüssel fehlt; nur den Schlüssel zu sichern ist ohne Datenbank nutzlos.

Im Queue-Modus müssen Hauptinstanz und alle Worker denselben N8N_ENCRYPTION_KEY verwenden, sonst können Worker die von der Hauptinstanz geschriebenen Zugangsdaten nicht entschlüsseln. Schreiben Sie dies vor einer Skalierung in die Deployment-Checkliste.

Ab n8n 3.0 wird die Rotation von Datenverschlüsselungsschlüsseln standardmäßig unterstützt; in 2.x muss N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true manuell aktiviert und auf allen Nodes einheitlich gesetzt werden. Vor der Rotation ein vollständiges Datenbankbackup erstellen; die offizielle Dokumentation weist außerdem darauf hin, nach Aktivierung des neuen Formats nicht auf eine ältere Version zurückzugehen. Der Einstieg liegt unter Settings > Data Encryption Keys.

6. Rotation und Minimalrechte

Schlüsselverwaltung ist kein einmaliger Vorgang, sondern kontinuierliche Rechtebegrenzung:

  • Nach Umgebung: Entwicklung, Test und Produktion mit unterschiedlichen Keys; Produktions-Keys nicht auf Entwicklungsrechnern.
  • Nach Projekt: ein Key pro Projekt, Verbrauch und Kontingent getrennt beobachten.
  • Nach Person: eigene Keys, bei Austritt einzeln widerrufen, keine gemeinsame Nutzung durch alle.
  • Kurze Laufzeit: Public-API-Keys mit Ablaufzeit; Modell-Keys ebenfalls regelmäßig rotieren.
  • Erst neu, dann alt löschen: neuen Key anlegen, Aufrufer aktualisieren, validieren, dann alten Key widerrufen.
  • Minimalrechte: bei Enterprise-Public-API-Keys nur nötige Scopes; Projektrollen nur mit den erforderlichen Rechten.
  • Zweckbindung: bei einigen Web-API-basierten Zugangsdaten lassen sich erlaubte HTTP-Domains konfigurieren, damit ein gestohlener Key nicht beliebige Adressen aufruft.
  • Audit: Erstellung, Nutzung und Löschung von Keys protokollieren, bei auffälligem Verbrauch alarmieren.

7. Teamrollen und gemeinsame Zugangsdaten

n8n kennt Instanzrollen wie Owner, Admin und Member; Projekte und Zugangsdaten lassen sich projektbezogen trennen. In der Community-Version liegen Zugangsdaten im persönlichen Bereich; Versionen mit Projektunterstützung erlauben Zugangsdaten im Projekt für Projektmitglieder. Benutzerdefinierte Rollen und fein granularere Rechte gehören zur Enterprise-Version; maßgeblich ist die offizielle Dokumentation.

Praktische Empfehlungen:

  1. Owner nur wenigen Personen geben; den Alltag mit Admin oder Member erledigen.
  2. Geschäftsworkflows und Zugangsdaten in Projekten ablegen, nicht im persönlichen Bereich.
  3. Zugangsdaten einheitlich als „Dienst-Umgebung-Zweck“ benennen, etwa „Gateway-Produktion-Kundenservice-Zusammenfassung“.
  4. Keine Login-Konten teilen und persönliche Keys nicht an Kollegen weitergeben.
  5. MFA aktivieren, in der Produktion HTTPS erzwingen und N8N_SECURE_COOKIE=true setzen.
  6. In der Produktion externe Task Runner verwenden; die offizielle Dokumentation markiert den internen Modus als nicht empfohlen und ab 3.0 als veraltet.

Die Enterprise-Version kann externe Secret-Speicher anbinden und Werte aus 1Password Connect, AWS Secrets Manager, Azure Key Vault, GCP Secrets Manager, HashiCorp Vault oder Infisical in Zugangsdatenfelder referenzieren. Referenzen werden nur im jeweiligen Feld aufgelöst und erscheinen nicht in anderen Workflow-Ausdrücken.

8. Häufige Fehlerbehebung

Symptom Mögliche Ursache Behandlung
Zugangsdaten nicht entschlüsselbar N8N_ENCRYPTION_KEY geändert oder alte Datenbank wiederhergestellt Ursprünglichen Schlüssel zurücksetzen; passendes Backup verwenden
Public API liefert 401 X-N8N-API-KEY fehlt oder ist abgelaufen Neuen Key erstellen, Header prüfen
Public API liefert 403 Enterprise-Scopes unzureichend Nötige Scopes wie workflow:read ergänzen
Modellaufruf liefert 401 Modell-Key falsch, abgelaufen oder Zugangsdaten nicht gewählt Key neu eintragen, Bindung des Nodes prüfen
Umgebungsvariable nicht lesbar Variable nicht in den Container übergeben oder Node-Zugriff gesperrt Compose-Umgebung und N8N_BLOCK_ENV_ACCESS_IN_NODE prüfen
Worker meldet Entschlüsselungsfehler Worker- und Hauptinstanz-Schlüssel weichen ab N8N_ENCRYPTION_KEY vereinheitlichen und neu starten

Beginnen Sie die Fehlersuche mit „Was wurde zuletzt geändert?“: Key-Wechsel, Base-URL-Änderung, Versionsupgrade und Datenbankmigration lösen am häufigsten Key-Probleme aus. Ändern Sie jeweils nur eine Variable und validieren Sie sofort mit einer minimalen Anfrage.

Häufige Fragen

Sind n8n API Key und OpenAI API Key dasselbe?

Nein. Der n8n API Key ruft die REST-API von n8n auf, Header X-N8N-API-KEY; ein OpenAI-kompatibler Key ruft Modellschnittstellen auf, liegt in den Zugangsdaten und wird vom Node als Bearer gesendet.

Unterstützt der n8n Public API Key Rechtebereiche?

Die Enterprise-Version unterstützt Scopes und kann auf konkrete Ressourcen und Aktionen begrenzen; offiziell wird empfohlen, nur notwendige Bereiche zu vergeben. Keys ohne Enterprise haben standardmäßig vollen Zugriff auf Kontoressourcen, daher nach Person und Zweck trennen und Ablaufzeiten setzen.

Was passiert bei einer Änderung von N8N_ENCRYPTION_KEY?

Bereits verschlüsselte Zugangsdaten lassen sich meist nicht mehr entschlüsseln. Der Wert sollte beim ersten Deployment festgelegt und gesichert werden; bei einer nötigen Änderung zuerst prüfen, ob die offizielle Schlüsselrotation genutzt werden kann, statt die Umgebungsvariable direkt zu ändern.

Kann man Keys über Umgebungsvariablen für Workflows bereitstellen?

Möglich, aber nicht empfehlenswert. Die n8n-Dokumentation weist darauf hin, dass Umgebungsvariablen nicht geschützt sind und für Nutzer sichtbar sein können. Besser sind Zugangsdaten oder ein externer Secret-Speicher; wenn Umgebungsvariablen nötig sind, mindestens N8N_BLOCK_ENV_ACCESS_IN_NODE aktivieren und Instanzzugriff begrenzen.

Ist ein gemeinsam genutzter Modell-Key im Team akzeptabel?

Nicht empfehlenswert. Ein gemeinsamer Key erlaubt keine Verbrauchszuordnung, ein Leak betrifft alle und ein einzelner Widerruf ist nicht möglich. Keys nach Projekt, Umgebung oder Person trennen und mit Kontingent- und Verbrauchsberichten des Gateways kombinieren; Kosten und Sicherheit werden kontrollierbarer.

Nächste Schritte

Das Key-System von n8n lässt sich in einem Satz merken: Public API Key verwaltet die Instanz, Modell-Key die Aufrufe, Verschlüsselungsschlüssel die Datenbank. Getrennt ablegen, getrennt rotieren und mit Projektrollen, Ablaufzeiten und Audits ergänzen. Für einen einheitlichen Modelleinstieg und Verbrauchsverwaltung können Sie sich im ZSQH AI Gateway registrieren; Modelle und Preise stehen auf der Seite Modellpreise.

Weiterlesen: