Hier erfährst du, wie du mit der Management-API externe Schlüssel für EKM verwaltest.

Zusammenfassung

Zugang

EKM-Endpunkte sind über die Management-API mit einem Admin-API-Schlüssel zugänglich. https://platform.openai.com/settings/organization/admin-keys (Verwende keinen normalen API-Schlüssel.) 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, und api.external_keys.read, um externe Schlüssel aufzulisten oder zu validieren. Ein einzelner Schlüssel benötigt beide Berechtigungen nur dann, wenn er sowohl Lese- als auch Schreibvorgänge ausführen muss.
Derzeit müssen wir deine Organisation per Feature-Flag für diese Endpunkte freischalten. Ob das Feature-Flag aktiviert ist, erkennst du daran, dass der bestehende Endpunkt „List Projects“ external_key_id zurückgibt: https://api.openai.com/v1/organization/projects.

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, neue Projekte für deine EKM-Workloads einzurichten. Falls du EKM für ein bestehendes Projekt aktivieren möchtest, können wir dich für dieses Feature freischalten. Bitte beachte die Best Practices, bevor du EKM für deine bestehenden Produktionsprojekte ausrollst.
- 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"
}

Einen externen Schlüssel löschen, der in deiner Organisation registriert ist

Hinweis: Du kannst einen externen Schlüssel nur löschen, wenn er keinen aktiven API-Projekten und keinem Workspace zugeordnet ist. Wenn er mit einem aktiven API-Projekt verknüpft ist, archiviere dieses Projekt zuerst. Wenn er mit einem Workspace verknüpft ist, kann der Schlüssel nicht gelöscht werden.

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.

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

Mit diesem Endpunkt kannst du Folgendes überprüfen:

Ob deine externe Cloud-Konfiguration nach Änderungen für OpenAI weiterhin gültig ist (du erhältst eine Erfolgsantwort).
Ob der Widerruf deines Schlüssels korrekt erfolgt ist, von OpenAI verarbeitet wird und nach Ablauf der einstündigen Cache-TTLs wirksam wird (du erhältst eine Fehlerantwort).

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"
}

[Eingeschränkt] Ein bestehendes Projekt mit einer externen Schlüssel-ID 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, neue API-Projekte für deine EKM-Workloads einzurichten. Wenn du EKM für alle deine bestehenden API-Projekte möchtest, wende dich an deinen Account-Direktor, und wir werden dich zur Feature-Flag hinzufügen. Bitte beachte die Best Practices, bevor du EKM für deine bestehenden Produktionsprojekte ausrollst.

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
}

EKM (Externe Schlüssel) in der Management-API

Zusammenfassung

Zugang

Nutzung

Beschränkungen

Endpunkte auf Organisationsebene

Einen externen Schlüssel in deiner Organisation registrieren

AWS

GCP

Azure

Einen externen Schlüssel löschen, der in deiner Organisation registriert ist

Beispielanfrage

Beispielantwort

Rufe die externen Schlüssel ab, die für deine Organisation registriert sind.

Beispielanfrage

Beispielantwort

Einen externen Schlüssel validieren

Beispielanfrage

Beispielantwort

Endpunkte auf Projektebene

Ein neues Projekt mit einer externen Schlüssel-ID erstellen

Beispielanfrage

Beispielantwort

[Eingeschränkt] Ein bestehendes Projekt mit einer externen Schlüssel-ID aktualisieren

Beispielanfrage

Alle Projekte in deiner Organisation auflisten

Beispielanfrage

Beispielantwort

War dieser Artikel hilfreich?