So erhalten Sie einen OpenAI API Key und beheben einen 401-Fehler „Invalid API Key“

Ein OpenAI-401-Fehler ist ein Authentifizierungsproblem, bedeutet jedoch nicht immer dasselbe. Die schnellste Lösung besteht darin, den Hostnamen der Anfrage zu ermitteln, zu bestätigen, welches Secret der laufende Prozess tatsächlich geladen hat, und anschließend anhand des Fehlertextes zwischen einem falschen Schlüssel, einem widerrufenen Schlüssel, einer Nichtübereinstimmung von Gateway-Anmeldedaten oder einer Blockierung durch eine IP-Allowlist zu unterscheiden.

Wenn Sie danach suchen, wie Sie einen OpenAI API Key erhalten, weil gerade eine Anfrage fehlgeschlagen ist, fügen Sie nicht blind ein neues Secret in dieselbe Konfiguration ein. Stellen Sie zuerst fest, ob die Anfrage an api.openai.com oder an ein OpenAI-kompatibles Gateway geht. Für diese beiden Endpunkte können unterschiedliche Anmeldedaten erforderlich sein.

Fügen Sie niemals einen vollständigen API Key in ein Ticket, einen Chat, einen Screenshot, ein Log oder diese Checkliste ein. Vergleichen Sie stattdessen einen sicher abgeleiteten Fingerabdruck oder das von Ihrem Anbieter angezeigte maskierte Suffix.

Was bedeutet „invalid API key“?

Es bedeutet, dass der Dienst, der die Anfrage erhalten hat, die für diese Anfrage übermittelten Anmeldedaten nicht authentifizieren konnte. Bei einer direkten OpenAI-Anfrage kann die offizielle Fehlermeldung Incorrect API key provided lauten. Zu den ersten Prüfungen von OpenAI gehören der Vergleich des maskierten Schlüssels in der Fehlermeldung mit dem vorgesehenen Schlüssel, die Sicherstellung, dass eine Anwendung nicht zwischen zwei Schlüsseln wechselt, und die Bestätigung der korrekten Organisationskonfiguration, wenn diese erforderlich ist. OpenAI’s incorrect-key guidance ist die maßgebliche Quelle für genau diese Meldung.

Der HTTP-Status allein reicht nicht aus, um die Ursache zu diagnostizieren. OpenAI dokumentiert beispielsweise, dass eine durch IP-Allowlisting blockierte Anfrage HTTP 401 mit dem Fehlertyp ip_not_authorized zurückgibt – selbst bei einem gültigen Schlüssel. Lesen Sie den Fehlertext, bevor Sie etwas rotieren. OpenAI’s IP allowlisting guide erläutert den Unterschied.

Die Fünf-Minuten-Checkliste zur Diagnose

Arbeiten Sie diese Prüfungen der Reihe nach durch. Halten Sie an, wenn die Belege auf eine Ursache hindeuten; mehrere Dinge gleichzeitig zu ändern, erschwert den Nachweis einer funktionierenden Lösung.

1. Bestätigen Sie den Endpunkt, bevor Sie den Schlüssel ändern

Dies ist die wichtigste Prüfung, wenn ein SDK eine konfigurierbare base_url hat.

• Eine Anfrage an https://api.openai.com/... benötigt OpenAI-API-Anmeldedaten.
• Eine Anfrage an ein Gateway oder einen Proxy benötigt die Anmeldedaten und das Authentifizierungsformat, die dieses Gateway dokumentiert.
• Eine Anfrage kann im Code „OpenAI-kompatibel“ aussehen, während sie dennoch an einen Nicht-OpenAI-Host gesendet wird.

Wie Sie einen OpenAI API Key erhalten, ist erst relevant, nachdem Sie bestätigt haben, dass die Anfrage tatsächlich an OpenAI geht. Wenn der Host ein Gateway ist, wird ein neu erstellter OpenAI-Schlüssel einen 401-Fehler dieses Gateways nicht beheben. Vergleichen Sie den konfigurierten Hostnamen, die SDK-Basis-URL, Bereitstellungsvariablen und jede Proxy-Konfiguration; protokollieren Sie dabei keine Authorization-Header.

Bei einem Routing-Setup für mehrere Modelle sollten Sie Endpunkt- und Schlüsselkonfiguration zusammenhalten. Der umfassendere OpenAI-compatible API troubleshooting guide behandelt Basis-URLs, Modellnamen, Streaming und routing-spezifische Prüfungen, nachdem dieser direkte Test der Anmeldedaten erfolgreich war.

2. Prüfen Sie, ob die Anwendung ein vorgesehenes Secret lädt

Häufige Ursachen eines Fehlers „invalid API key“ sind banale Konfigurationsfehler:

• OPENAI_API_KEY ist im laufenden Prozess nicht gesetzt, obwohl er auf Ihrem Laptop vorhanden ist.
• Eine Bereitstellung verweist noch auf eine ältere Secret-Version.
• Eine .env-Datei wird nicht in der Umgebung geladen, die die Anfrage tatsächlich ausführt.
• Der Wert enthält unbeabsichtigte Anführungszeichen, Leerzeichen, einen Zeilenumbruch oder einen kopierten Platzhalter.
• Ein Codepfad verwendet einen Bibliotheksstandard, während ein anderer den Schlüssel oder die Basis-URL überschreibt.

Verwenden Sie in einer privaten Debug-Umgebung einen nicht umkehrbaren Fingerabdruck. So können Sie vergleichen, welches Secret verschiedene Prozesse geladen haben, ohne das Secret selbst auszugeben:

import crypto from "node:crypto";

const key = process.env.OPENAI_API_KEY?.trim();

if (!key) {
  throw new Error("OPENAI_API_KEY is not set in this process");
}

const fingerprint = crypto
  .createHash("sha256")
  .update(key)
  .digest("hex")
  .slice(0, 12);

console.info({ keyConfigured: true, keyLength: key.length, fingerprint });

Vergleichen Sie den Fingerabdruck zwischen lokaler Entwicklung, CI, Staging, Workern und Produktion. Vergleichen oder speichern Sie nicht den vollständigen Schlüssel.

3. Testen Sie eine direkte Anfrage in derselben Laufzeitumgebung

Führen Sie eine minimale Anfrage auf demselben Rechner, Container oder Job aus, der fehlschlägt. Dadurch wird das Laden der Zugangsdaten von der Anwendungslogik getrennt. Der folgende Befehl verwendet den Standard-Bearer-Header, lässt den Schlüssel jedoch bewusst in einer Umgebungsvariable:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Interpretieren Sie das Ergebnis sorgfältig:

• Dieselbe 401-Antwort aus derselben Laufzeitumgebung weist auf die Zugangsdaten, den Endpunkt, die Organisations-/Projekteinstellung oder die Netzwerkrichtlinie hin.
• Eine erfolgreiche Antwort weist auf die Anwendungskonfiguration hin: eine andere Laufzeitumgebung, eine Base-URL-Überschreibung, doppelte Client-Erstellung oder eine andere Umgebungsvariable.
• Eine ip_not_authorized-Antwort ist ein Problem mit der IP-Allowlist und kein Hinweis darauf, dass der Schlüsseltext ungültig ist.

Ersetzen Sie diesen Test nicht durch eine Browser-Anfrage. OpenAI rät davon ab, API-Schlüssel in Browsern oder mobilen Apps bereitzustellen, da sie offengelegt und von anderen verwendet werden können. Senden Sie Anfragen stattdessen über Ihr eigenes Backend. OpenAIs Sicherheitsleitfaden für API-Schlüssel erklärt, warum.

4. Prüfen Sie, ob der Schlüssel widerrufen, gelöscht, offengelegt oder abgelaufen ist

OpenAI-API-Geheimnisse werden nur bei der Erstellung vollständig angezeigt. Wenn Sie das Geheimnis nicht gespeichert haben, können Sie es nicht über das Dashboard wiederherstellen; erstellen Sie ein neues und aktualisieren Sie die Anwendung. Gelöschte Schlüssel können nicht verwendet werden. OpenAIs Artikel zur Schlüsselverwaltung bestätigt beide Verhaltensweisen.

Wenn Sie eine neue Integration einrichten, anstatt sich von einem Vorfall zu erholen, verwenden Sie den ergänzenden Leitfaden für Open AI API keys in der Produktion für eine umfassendere Checkliste zu Einrichtung, Sicherheit und Betrieb.

Betrachten Sie diese Ereignisse als Grund für eine Rotation, nicht für endlose Wiederholungsversuche:

• Der Schlüssel wurde gelöscht oder absichtlich widerrufen.
• Der Schlüssel wurde möglicherweise in ein Repository eingecheckt, in einer Nachricht gesendet, in eine Client-App eingebettet oder anderweitig offengelegt. OpenAI gibt an, Schlüssel zu deaktivieren, die es im öffentlichen Internet oder innerhalb einer App-Store-App als geleakt erkennt.
• Ein Projektschlüssel wurde mit einem Ablaufdatum erstellt, und dieses Datum ist überschritten.
• Eine Bereitstellung verweist nach einer geplanten Rotation auf einen vorherigen Schlüssel.

Erstellen Sie für einen Ersatz den neuen Schlüssel im vorgesehenen Projekt, schreiben Sie ihn in den richtigen Secret Store, stellen Sie ihn bereit, bestätigen Sie eine minimale Anfrage und widerrufen Sie dann den alten Schlüssel. OpenAI empfiehlt Ablaufdaten und einen regelmäßigen Rotationsprozess; außerdem werden getrennte Schlüssel statt gemeinsam genutzter Team-Zugangsdaten empfohlen. Aktuelle Sicherheitsempfehlungen ansehen.

5. Prüfen Sie Projektmitgliedschaft und Schlüsselberechtigungen

Wenn Sie einen Schlüssel erstellen oder sehen können, eine Team-Workload aber weiterhin fehlschlägt, prüfen Sie die Projektgrenze, bevor Sie davon ausgehen, dass das Geheimnis fehlerhaft formatiert ist. OpenAI-Projekte verwalten API-Schlüssel, Mitglieder, Servicekonten, Modellzugriff und Ausgabenlimits. Benutzereigene Schlüssel können auf vollständige, eingeschränkte oder schreibgeschützte Berechtigungen gesetzt werden. OpenAIs Projektleitfaden dokumentiert die verfügbaren Kontrollen.

Stellen Sie diese Fragen:

1. Stammt der Schlüssel aus demselben Projekt wie die Ressourcen der Anwendung und die vorgesehene Nutzung?
2. Ist das Servicekonto oder der Benutzer noch Mitglied dieses Projekts?
3. Verfügt der Schlüssel über die Berechtigungen für Endpunkt/Ressource, die der Aufruf benötigt?
4. Falls der Fehler eine Organisation angibt: Ist der Client für die vorgesehene Organisation statt für eine veraltete konfiguriert?

Berechtigungs- und Projektprobleme können eine spezifischere Meldung oder einen anderen Statuscode als Incorrect API key provided haben. Bewahren Sie die Request-ID und den bereinigten Body des Fehlers für den Verantwortlichen Ihrer Plattform oder den OpenAI Support auf, statt zu raten.

6. Schließen Sie IP-Allowlisting aus, bevor Sie einen gültigen Schlüssel rotieren

Eine OpenAI-Organisation kann API-Datenverkehr auf genehmigte IP-Bereiche beschränken. Eine Anfrage von jeder anderen Adresse wird mit HTTP 401 und ip_not_authorized abgelehnt, selbst wenn die Zugangsdaten selbst gültig sind. Das macht dies zu einem besonders leicht falsch zu diagnostizierenden 401-Fehler.

Wenn der Fehlertyp ip_not_authorized lautet:

1. Ermitteln Sie die tatsächliche ausgehende IP-Adresse der Workload – nicht die öffentliche IP-Adresse des Entwicklerlaptops.
2. Vergleichen Sie sie mit der konfigurierten Allowlist und prüfen Sie, ob sich eine Cloud-NAT-, Serverless-Egress-Adresse oder ein Proxy geändert hat.
3. Aktualisieren Sie den zulässigen Bereich über die entsprechenden Organisationskontrollen.
4. Warten Sie das dokumentierte Weitergabezeitfenster ab, bevor Sie den minimalen Test erneut ausführen.

Lassen Sie den Schlüssel unverändert, bis dieser Zweig widerlegt ist. Die Rotation eines gültigen Schlüssels fügt dem Vorfall nur eine zweite Variable hinzu.

So erhalten Sie nach einem 401 einen OpenAI API key

Wenn die Belege zeigen, dass das Zugangstoken fehlt, gelöscht, kompromittiert oder abgelaufen ist, folgen Sie diesem kurzen Wiederherstellungsablauf:

1. Öffnen Sie die OpenAI API key page in der vorgesehenen Organisation und dem vorgesehenen Projekt.
2. Erstellen Sie einen neuen geheimen Schlüssel mit dem geringstmöglichen, für die Arbeitslast angemessenen Zugriff.
3. Speichern Sie ihn direkt in einem serverseitigen Secret Manager oder als Deployment-Secret; legen Sie ihn nicht in Browsercode, einer eingecheckten .env-Datei oder einem freigegebenen Dokument ab.
4. Aktualisieren Sie zunächst eine Umgebung und führen Sie die minimale direkte Anfrage aus.
5. Übernehmen Sie die Änderung in die verbleibenden Umgebungen und bestätigen Sie, dass sich der Fingerabdruck erwartungsgemäß geändert hat.
6. Widerrufen Sie den vorherigen Schlüssel erst, nachdem der Ersatz verifiziert wurde, es sei denn, der alte Schlüssel ist offengelegt – widerrufen Sie ihn in diesem Fall sofort und untersuchen Sie die Nutzung.

So erhalten Sie für eine Wiederherstellung sicher einen OpenAI API key. Dies ist kein Grund, einen Schlüssel über Teammitglieder oder Umgebungen hinweg zu teilen. Verwenden Sie getrennte Projekt-/Benutzer- oder Service-Account-Zugangsdaten, damit ein zukünftiger 401 einen kleineren Schadensradius hat.

Ein gateway-spezifischer 401 erfordert eine andere Frage

Wenn eine Codebasis ein OpenAI-kompatibles SDK mit einer benutzerdefinierten base_url verwendet, beginnen Sie mit der Frage: Welcher Dienst hat die Anfrage empfangen? Ein Gateway kann seinen eigenen 401 zurückgeben, bevor es etwas an OpenAI weiterleitet. Prüfen Sie in der eigenen Dokumentation des Gateways die Gateway-Zugangsdaten, den Mandanten/Workspace, die API-Basis-URL und die Modellkennung.

Sobald die Anfrage authentifiziert ist, verwenden Sie den Flatkey API quickstart für ein fokussiertes Setup eines kompatiblen Routers oder kehren Sie zum OpenAI-compatible API troubleshooting guide für Prüfungen von Modell, Streaming und Basis-URL zurück. Bewahren Sie einen direkten OpenAI-Schlüssel und einen Gateway-Schlüssel in getrennt benannten Secret-Variablen auf, damit ein zukünftiger Vorfall anhand der Konfiguration und nicht durch Versuch und Irrtum offensichtlich wird.

Bevor Sie den Vorfall abschließen

• [ ] Der Hostname und die base_url stimmen mit dem Aussteller der Zugangsdaten überein.
• [ ] Der Produktionsprozess hat den erwarteten Secret-Fingerabdruck geladen.
• [ ] Der Schlüssel wurde nicht gelöscht, widerrufen, offengelegt oder ist nicht abgelaufen.
• [ ] Projektmitgliedschaft und Schlüsselberechtigungen sind für die Arbeitslast korrekt.
• [ ] ip_not_authorized wurde ausgeschlossen oder die Allowlist wurde aktualisiert.
• [ ] Eine minimale Anfrage funktioniert aus der fehlschlagenden Laufzeitumgebung.
• [ ] In Logs, Versionsverwaltung, Tickets oder Chats ist kein vollständiges Zugangstoken erschienen.
• [ ] Der alte Schlüssel wurde erst nach Verifizierung des Ersatzes widerrufen, sofern er nicht offengelegt war.

Wie man einen OpenAI API key erhält, ist eine nützliche Einrichtungsaufgabe; die Diagnose von Host, Secret-Quelle, Lebenszyklus und Netzwerkrichtlinie macht aus der Behebung eines 401 eine dauerhafte Reparatur für die Produktion.

Häufig gestellte Fragen

Was bedeutet „invalid API key“ bei OpenAI?

Das bedeutet, dass der Dienst, der die Anfrage verarbeitet, die übermittelten Zugangsdaten nicht authentifizieren konnte. Vergleichen Sie bei der genauen Meldung Incorrect API key provided den vorgesehenen Schlüssel mit dem maskierten Wert in der Fehlermeldung, stellen Sie sicher, dass die App nicht zwei Schlüssel verwendet, und prüfen Sie die korrekte Organisationskonfiguration. Ein anderer Fehlertyp wie ip_not_authorized weist auf eine andere Ursache hin.

Wie erhalte ich einen OpenAI API key, wenn der alte nicht mehr funktioniert?

Erstellen Sie im vorgesehenen OpenAI-Projekt einen neuen geheimen Schlüssel, speichern Sie ihn in einem serverseitigen Secret Store, aktualisieren Sie das aktive Deployment und verifizieren Sie eine minimale Anfrage, bevor Sie den alten Schlüssel widerrufen. Sie können den vollständigen Wert eines vorhandenen Schlüssels nicht mehr abrufen, nachdem der Erstellungsbildschirm geschlossen wurde.

Kann ich einen OpenAI-401 beheben, indem ich einen neuen Schlüssel in Browser-JavaScript einfüge?

Nein. Ein Browser oder eine mobile App ist der falsche Ort für ein Provider-Secret. Leiten Sie Anfragen über Ihr Backend und speichern Sie das Secret in serverseitiger Konfiguration oder einem Secret Manager.

Warum gibt ein gültiger OpenAI-Schlüssel 401 ip_not_authorized zurück?

Die OpenAI-IP-Allowlist kann Anfragen von einer Adresse ablehnen, die nicht auf der Allowlist der Organisation steht. Prüfen Sie die tatsächliche ausgehende IP-Adresse des Servers oder der Cloud-Arbeitslast und vergleichen Sie sie dann mit den konfigurierten IP-Bereichen.

Warum hat ein neuer OpenAI-Schlüssel einen Gateway-401 nicht behoben?

Ein Gateway-Endpunkt kann einen eigenen API-Schlüssel und eine eigene Konfiguration erfordern. Bestätigen Sie den Hostnamen der Anfrage und verwenden Sie die vom Betreiber dieses Endpunkts ausgestellten Zugangsdaten; ein direkter OpenAI-Schlüssel authentifiziert keine Anfrage an jede OpenAI-kompatible API.

Offizielle Quellen

• OpenAI: Incorrect API key provided
• OpenAI: Best practices for API key safety
• OpenAI: Managing projects in the API platform
• OpenAI: IP allowlisting for the OpenAI API
• OpenAI: Where do I find my OpenAI API key?