Zusammenfassung
Zugang
EKM-Endpunkte sind in der Management-API über einen Admin-API-Schlüssel zugänglich. https://platform.openai.com/settings/organization/admin-keys (Keinen normalen API-Schlüssel verwenden.) Admin-API-Schlüssel stehen Eigentümer:innen der Organisation zur Verfügung.
Verwende
api.external_keys.write, um externe Schlüssel zu erstellen oder zu löschen, undapi.external_keys.read, um externe Schlüssel aufzulisten, abzurufen oder zu validieren. Ein einzelner Schlüssel benötigt beide Berechtigungen nur dann, wenn er sowohl Lese- als auch Schreibvorgänge ausführen muss.
Nutzung
Deine EKM-Konfiguration wird über einen neuen Endpunkt auf Organisationsebene registriert: https://api.openai.com/v1/organization/external_keys.
Die Registrierung deiner EKM-Konfiguration liefert eine external_key_id im Format extkey_xxxx.
EKM-Konfigurationen werden auf Projektebene aktiviert, indem die external_key_id im Body an den bestehenden Endpunkt zum Erstellen von Projekten übergeben wird: https://api.openai.com/v1/organization/projects sendest.
Beschränkungen
Du musst EKM zuerst in einem neuen Projekt über die Management-API testen.
Wir empfehlen, für deine EKM-Workloads neue Projekte anzulegen. Beachte die folgenden Empfehlungen, bevor du EKM in bestehenden Produktionsprojekten einführst.
Teste zunächst alle API-Funktionen, die du in der Produktionsumgebung nutzt, in deinem EKM-API-Testprojekt.
Führe EKM schrittweise ein, statt es gleichzeitig für alle produktiven API-Projekte zu konfigurieren.
Endpunkte auf Organisationsebene
Einen externen Schlüssel in deiner Organisation registrieren
AWS
Beispielanfrage:
type: string – immer "aws"
name: string – Ein benutzerfreundlicher Name für deine Konfiguration
role_arn: string – Die Rollen-ARN, die OpenAI in deiner Cloud übernehmen wird
kms_arn: string – Die ARN des Schlüsselverwaltungssystems für den von dir verwalteten Hauptschlüssel
external_id: string – Deine Organisations-ID oder API-Projekt-ID
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "aws",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<12_DIGIT_ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": "<your org id or project id>"
}'Beispielantwort:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "aws",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"external_id": "<your org id or project id>"
}GCP
Beispielanfrage:
type: string – immer "gcp",
name: string – Ein benutzerfreundlicher Name für deine Konfiguration
workload_identity_project_number: string – Die numerische GCP-Projektnummer des Projekts, in dem du die Workload-Identität von OpenAI registriert hast
workload_identity_pool_id: string – Der Pool, der den Workload-Identitätsanbieter enthält, den du für OpenAI registriert hast
workload_identity_provider_id: string – Der Workload-Identitätsanbieter, den du für OpenAI registriert hast
audience: string – Die Zielgruppe, die OpenAI im Token übergeben soll, wenn wir über deinen GCP STS eine Rolle übernehmen
kms_project_id: string – Der Name des GCP-Projekts, in dem sich dein KMS befindet
kms_key_ring_name: string – Der Schlüsselbund des Schlüsselverwaltungssystems, der den von dir verwalteten Hauptschlüssel enthält
kms_key_name: string – Der Name des Hauptschlüssels des Schlüsselverwaltungssystems
kms_key_location: string – Die Region, in der sich dein Hauptschlüssel des Schlüsselverwaltungssystems befindet
Wenn sich dein KMS in einem anderen GCP-Projekt befindet als dem, in dem du die Workload-Identität von OpenAI registriert hast, stelle sicher, dass KMS zumindest auch im Projekt mit der Workload-Identität aktiviert ist. Rufe dazu https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview auf.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "gcp",
"name": "GCP EKM Config",
"workload_identity_project_number": "123456789012",
"workload_identity_pool_id": "openai-azure",
"workload_identity_provider_id": "openai-ekm-service-role",
"audience": "<your org id or project id>",
"kms_project_id": "adjective-noun-12345",
"kms_key_name": "openai-kms-key",
"kms_key_ring_name": "openai-kms-key-ring",
"kms_key_location": "us-east1"
}'Beispielantwort:
{
"id": "extkey_xxxxxx",
"object": "organization.external_key",
"created_at": 1746174349,
"api_project_ids": [],
"type": "gcp",
"name": "GCP EKM Config",
"workload_identity_project_number": "123456789012",
"kms_key_ring_name": "openai-kms-key-ring",
"kms_key_name": "openai-kms-key",
"kms_key_location": "us-east1",
"audience": "<your org id or project id>",
"kms_project_id": "adjective-noun-12345",
"workload_identity_pool_id": "openai-azure",
"workload_identity_provider_id": "openai-ekm-service-role"
}Azure
Beispielanfrage:
type: string – immer "azure",
name: string – Ein benutzerfreundlicher Name für deine Konfiguration
tenant_id: string – Deine Azure-Tenant-UUID
vault_uri: string – Die URI des Azure-Tresors, der den von dir verwalteten Hauptschlüssel enthält
key_name: string – Der Name des Azure Key Vault-Masterschlüssels, den du verwaltest.
Dieser muss die Form <org-xxx>--<any_name> haben,
wobei org-xxx deine OpenAI-Organisations-ID ist, die du unter https://platform.openai.com/settings/organization/generalfinden kannst
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "azure",
"name": "Azure EKM Config",
"tenant_id": "<UUID>",
"vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
"key_name": "org-xxx--some-key"
}'Beispielantwort:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746174377,
"api_project_ids": [],
"type": "azure",
"name": "Azure EKM Config",
"tenant_id": "<UUID>",
"vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
"key_name": "org-xxx--some-key"
}OCI
Richte einen aktivierten AES-256-Schlüssel ein und gewähre OpenAI Zugriff. Füge dem Schlüssel den Freiform-Tag openai_organization_id hinzu und gib deine OpenAI-Organisations-ID als Wert an. Die Anleitung findest du unter „OCI Vault für Enterprise Key Management konfigurieren“.
Beispielanfrage:
type: string – immer "oci"
purpose: string – ohne Angabe gilt der Standardwert "ekm"
name: string – Ein benutzerfreundlicher Name für deine Konfiguration
region: string – die OCI-Region, in der sich dein Vault und dein Schlüssel befinden
vault_ocid: string – die vollständige OCID deines Vaults
key_ocid: string – die vollständige OCID deines AES-256-Schlüssels
Gib für EKM keine key_version_ocid an.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'Beispielantwort:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}Bei Erfolg gibt die API HTTP 200 zurück. Speichere den zurückgegebenen id-Wert und verwende ihn als external_key_id, wenn du ein Projekt erstellst. Auch OCI-Registrierungen kannst du mit den bestehenden Operationen auflisten, abrufen, validieren und löschen.
Verwende für die PSP-Wiederherstellung eine separate RSA-3072-Registrierung mit purpose: "psp_decryption" und dem exakten Wert für key_version_ocid. Setze psp_decryption_key_id auf die Registrierungs-ID bei OpenAI. Für diesen RSA-Schlüssel braucht OpenAI nur Lesezugriff auf Metadaten und öffentliche Schlüssel. Die vollständige Anleitung findest du unter Asymmetrische Schlüssel einrichten – OCI Vault.
Einen externen Schlüssel löschen, der in deiner Organisation registriert ist
Hinweis: Du kannst eine Registrierung erst löschen, wenn sie von keinem aktiven Projekt und keinem Workspace mehr verwendet wird. Archiviere bei EKM zuerst die zugehörigen API-Projekte. Eine EKM-Registrierung, die mit einem Workspace verknüpft ist, bleibt vor dem Löschen geschützt. Ersetze oder entferne für die PSP-Wiederherstellung den Wert von psp_decryption_key_id in jedem aktiven Projekt, das auf die Registrierung verweist. Danach kannst du die Registrierung löschen. Wenn du eine OpenAI-Registrierung löschst, bleibt der Cloud-Schlüssel erhalten.
Beispielanfrage
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Beispielantwort
{
"id": "extkey_xxxxx",
"object": "organization.external_key.deleted",
"created_at": 1746127808,
"api_project_ids": [],
"type": "aws",
"account_number": "123456789012",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"name": "AWS EKM Config",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}Rufe die externen Schlüssel ab, die für deine Organisation registriert sind.
Ohne „purpose“-Filter enthält die Liste sowohl Registrierungen für EKM als auch Registrierungen für die PSP-Wiederherstellung. Verwende ?purpose=ekm oder ?purpose=psp_decryption, um nach Zweck zu filtern.
Beispielanfrage
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Beispielantwort
{
"object": "list",
"data": [
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746127808,
"api_project_ids": [],
"type": "aws",
"name": "AWS EKM Config",
"account_number": "123456789012",
"kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
"role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}
],
"first_id": "extkey_xxxx",
"has_more": false,
"last_id": "extkey_xxxx"
}Einen externen Schlüssel validieren
Prüfe mit der Validierung, ob OpenAI weiterhin auf deinen Cloud-Schlüssel zugreifen kann.
Bei EKM prüft OpenAI, ob sich mit dem Schlüssel Daten ver- und entschlüsseln lassen. Informationen zum Widerruf und zur Zwischenspeicherung findest du im Leitfaden zum Lebenszyklus von Schlüsseln.
Für die PSP-Wiederherstellung ruft OpenAI den öffentlichen Schlüssel der registrierten Version ab und vergleicht ihn mit der gespeicherten Kopie. Eine erfolgreiche Validierung bestätigt nicht, dass deine Wiederherstellungsidentität Daten entschlüsseln kann. Wenn die Validierung fehlschlägt, bleibt die gespeicherte Kopie des öffentlichen Schlüssels erhalten.
Wenn du eine Registrierung mit GET abrufst, erhältst du die gespeicherte Konfiguration. Die API prüft dabei den Zugriff auf deinen Cloud-Schlüssel nicht erneut.
Beispielanfrage
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Beispielantwort
{
"status": "success"
}Oder es ist ein Fehler seitens deines Cloud-Anbieters aufgetreten.
Endpunkte auf Projektebene
Ein neues Projekt mit einer externen Schlüssel-ID erstellen
Dies funktioniert wie der bestehende Endpunkt zum Erstellen von Projekten, jedoch mit dem zusätzlichen Parameter external_key_id in der Anfrage und der Antwort.
Beispielanfrage
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
"name": "Some Project",
"external_key_id": "extkey_xxxx"
}'Beispielantwort
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Eine externe Schlüssel-ID in einem bestehenden Projekt aktualisieren
Dies funktioniert wie der bestehende Endpunkt zum Aktualisieren von Projekten, jedoch mit dem zusätzlichen Parameter external_key_id in der Anfrage und Antwort.
Wir empfehlen, für deine EKM-Workloads neue API-Projekte anzulegen. Beachte die folgenden Empfehlungen, bevor du EKM in bestehenden Produktionsprojekten einführst.
Teste zunächst alle API-Funktionen, die du in der Produktionsumgebung nutzt, in deinem EKM-API-Testprojekt.
Führe EKM schrittweise ein, statt es gleichzeitig für alle produktiven API-Projekte zu konfigurieren.
Beispielanfrage
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects/proj_xxx" \
-d '{
"external_key_id": "extkey_xxxx"
}'Alle Projekte in deiner Organisation auflisten
Dies ist derselbe Endpunkt wie bisher, allerdings enthält die API-Antwort zusätzlich external_key_id.
Beispielanfrage
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Beispielantwort
{
"object": "list",
"data": [
{
"object": "organization.project",
"id": "proj_xxxx",
"name": "Project Name",
"external_key_id": "extkey_xxxx",
"created_at": 1717798982,
"archived_at": null,
"status": "active"
}
],
"first_id": "proj_xxxx",
"last_id": "proj_xxxx",
"has_more": true
}