Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

API-Schlüssel und Dienstkonten

Wähle die passende Identität und die zugehörigen Zugangsdaten für die Entwicklung, für Anwendungen und für die Automatisierung.

Ein API-Schlüssel ist ein geheimer Wert, mit dem du Anfragen authentifizierst. Ein Dienstkonto ist eine Identität für eine Anwendung oder einen automatisierten Workload. Es ist keiner Person zugeordnet. Ein Dienstkonto kann eigene API-Schlüssel haben. Konto und Schlüssel erfüllen bei der Authentifizierung also unterschiedliche Aufgaben.

Verwende für deine eigene Entwicklungsarbeit einen Projektschlüssel, der zu deinem Benutzerkonto gehört. Verwende ein Dienstkonto für eine Anwendung oder Automatisierung, die eigene Berechtigungen und einen eigenen Lebenszyklus haben soll. Verwende einen Admin-API-Schlüssel, um deine Organisation über die Admin-APIs zu verwalten.

Die passende Identität auswählen

Workload Identität und Zugangsdaten Begründung
Eigene lokale Entwicklung oder erste Versuche Dein Benutzerkonto und ein Projekt-API-Schlüssel Für die Anfragen gelten deine Zugriffsrechte im Projekt.
Eine bereitgestellte Anwendung, ein geplanter Job oder ein CI-Workflow Ein Dienstkonto im Projekt und dessen API-Schlüssel Der Workload hat eine eigene Identität, die von den persönlichen Konten im Entwicklungsteam unabhängig ist.
Ein Workload mit einem von OpenAI unterstützten Identitätsanbieter Ein Dienstkonto im Projekt mit Identitätsföderation für Workloads Der Workload kann sich authentifizieren, ohne einen langlebigen OpenAI-API-Schlüssel zu speichern.
Eine Automatisierung, die Projekte erstellt oder deren Dienstkonten und Schlüssel verwaltet Ein Admin-API-Schlüssel Für die Verwaltung der Organisation gelten eigene administrative Endpunkte und Berechtigungen.

Für einen persönlichen Schlüssel gelten die Zugriffsrechte der Person, der er gehört. Teile einen persönlichen Schlüssel nicht im Team. Verwende die Identität einer einzelnen Person auch nicht als dauerhafte Identität einer Anwendung im Produktivbetrieb.

Ein Dienstkonto gehört zu einem Projekt. Gib jedem Workload die Identität und die Zugriffsrechte, die er innerhalb dieses Projekts benötigt. Mit separaten Projekten kannst du Ressourcen, Mitgliedschaften und Nutzung nach Anwendung oder Umgebung trennen. Mit separaten Dienstkonten innerhalb eines Projekts kannst du Workloads unterscheiden, ohne ein weiteres Projekt anzulegen.

Berechtigungen und Geltungsbereich verstehen

Bei einem API-Schlüssel zählen sowohl die Berechtigungen des Schlüssels als auch die des zugehörigen Kontos. Über den Geltungsbereich kannst du die zulässigen Aktionen eines Schlüssels einschränken. Dadurch erhält der Schlüssel keine Berechtigungen, die dem Benutzer- oder Dienstkonto fehlen. Auch ein uneingeschränkter Schlüssel kann nur die tatsächlich wirksamen Berechtigungen des zugehörigen Kontos nutzen.

Weise einem Dienstkonto nur die Rollen zu, die sein Workload benötigt. Schränke anschließend bei Bedarf seine Schlüssel ein. Der Leitfaden zu Berechtigungen und Rollen erklärt das Autorisierungsmodell. Im Leitfaden zu Dienstkonten mit Terraform findest du eine Konfiguration, die eine Identität erstellt, ihr eine benutzerdefinierte Rolle zuweist und einen Schlüssel mit eingeschränktem Geltungsbereich ausstellt.

Ein Admin-API-Schlüssel erfüllt einen anderen Zweck als der Schlüssel eines Workloads im Projekt. Bewahre den Admin-API-Schlüssel in dem vertrauenswürdigen Dienst auf, der Ressourcen bereitstellt und verwaltet. Verwende für Modellanfragen der Anwendung die Zugangsdaten ihres Dienstkontos im Projekt.

Projekt- und Schlüsselverwaltung automatisieren

Wenn deine Anwendung Projekte für deine Kundschaft bereitstellt, kannst du jedem Workload über ein Dienstkonto im jeweiligen Projekt eine eigene Identität geben. Diese ist unabhängig davon, wer im Entwicklungsteam die Bereitstellung ausführt. Dein Bereitstellungsdienst verwaltet das Projekt und dessen Dienstkonten über die Admin-APIs. Die bereitgestellte Anwendung verwendet ihre eigenen Zugangsdaten für das Projekt.

Für die Verwaltung stehen dir folgende Operationen zur Verfügung.

Operation Zweck
Projekt erstellen Erstelle das Projekt, zu dem die Ressourcen und das Dienstkonto des Workloads gehören.
Dienstkonto erstellen Erstelle die Identität des Workloads in diesem Projekt. Mit der Option create_service_account_only erstellst du das Dienstkonto ohne Standardrollen und ohne anfänglichen API-Schlüssel.
API-Schlüssel für ein Dienstkonto erstellen Stelle für ein bestehendes Dienstkonto einen Schlüssel aus. Lege bei Bedarf Geltungsbereiche und ein Ablaufdatum fest.
Projekt-API-Schlüssel verwalten Liste vorhandene Projektschlüssel auf, rufe sie ab, aktualisiere oder widerrufe sie. Das gilt auch für Schlüssel von Dienstkonten.

Über die Endpunkte zur Verwaltung von Projekt-API-Schlüsseln kannst du keine persönlichen Projektschlüssel im Namen einer anderen Person erstellen. Um Schlüssel programmgesteuert zu erstellen, verwende ein Dienstkonto und den zugehörigen Endpunkt zur Schlüsselerstellung.

Wenn du ein Dienstkonto ohne Standardrollen erstellst, erhält es dadurch keine Berechtigung für Modellanfragen. Weise dem Konto die erforderlichen Berechtigungen zu, bevor du seine Zugangsdaten verwendest. Beim Erstellen von Schlüsseln gelten auch die Schlüsselrichtlinien der Organisation und des Projekts. Ein Dienstkonto kann diese Richtlinien nicht umgehen.

Zugangsdaten über ihren gesamten Lebenszyklus verwalten

Die API gibt den vollständigen Wert eines Dienstkontoschlüssels nur bei seiner Erstellung zurück. Speichere ihn in deinem Secret Manager und stelle ihn dem Workload auf dem Server zur Verfügung. Halte geheime Schlüssel aus Browsercode, mobilen Apps, der Versionsverwaltung, Protokollen und Antworten an deine Kundschaft heraus.

Lege ein Ablaufdatum fest, das den Richtlinien deiner Organisation und deines Projekts entspricht. Um einen Schlüssel zu rotieren, stelle einen Ersatzschlüssel aus und aktualisiere den Workload. Prüfe, ob der Workload mit dem neuen Schlüssel funktioniert, und widerrufe dann den bisherigen Schlüssel. Die Identität des Dienstkontos kann beim Schlüsselwechsel bestehen bleiben.

Überprüfe die Zugriffsrechte des Workloads, wenn sich seine Aufgaben ändern. Widerrufe seine Zugangsdaten, wenn du ihn außer Betrieb nimmst. Die Empfehlungen für API-Schlüssel im Produktivbetrieb erläutern die Vorgaben zur Schlüsselverwaltung und zur Gültigkeitsdauer. Der Leitfaden zur Identitätsföderation für Workloads beschreibt die Authentifizierung ohne gespeicherten API-Schlüssel.