OpenAI

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

Externe Schlüssel für EKM mit der Management-API verwalten

Aktualisiert: 4 days ago

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 Organisationseigentümern 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.

  • Wir müssen deine Organisation derzeit per Feature-Flag für diese Endpunkte freischalten. Du weißt, dass du das Feature-Flag hast, wenn **external_key_id **vom vorhandenen List-Projects-Endpunkt zurückgegeben wird: https://api.openai.com/v1/organization/projects

Nutzung

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 zuerst alle API-Funktionen, die du nutzt, in deinem EKM-Testprojekt.

    • Wende ein schrittweises Rollout an, anstatt EKM sofort für alle Produktionsprojekte gleichzeitig zu aktivieren.

Endpunkte auf Organisationsebene

Einen externen Schlüssel in deiner Organisation registrieren

AWS

Beispielanfrage

  • Typ: 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 12-stellige GCP-Projektnummer, unter der 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 in dem Projekt, das die Workload-Identität von OpenAI enthält, zumindest KMS aktiviert ist, indem du https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview aufrufst. 

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

  • Typ: 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. 

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 keinem aktiven Projekt zugeordnet ist. Wenn er mit einem aktiven Projekt verknüpft ist, musst du dieses Projekt zuerst archivieren.

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

Du kannst diesen Endpunkt verwenden, um mehrere Dinge zu überprüfen.

  • Deine externe Cloud-Konfiguration bleibt bei OpenAI gültig, nachdem du Änderungen vorgenommen hast (du erhältst eine Erfolgsmeldung).

  • Dein Schlüssel-Widerruf ist korrekt durchgeführt, wird von OpenAI verarbeitet und tritt in Kraft, sobald die 1-stündigen Cache-TTLs abgelaufen sind (du wirst dann eine Fehlermeldung erhalten).

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": "project",
  "id": "proj_xxxxx",
  "title": "Some Project",
  "external_key_id": "extkey_xxxxx",
  "created": 1740012721,
  "organization_id": "org-xxxxx",
  "is_initial": false,
  "geography": null,
  "scale_tier_enabled": false,
  "disable_user_api_keys": false,
  "zdr_type": null,
}

[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 zuerst alle API-Funktionen, die du nutzt, in deinem EKM-Testprojekt.

  • Wende ein schrittweises Rollout an, anstatt EKM sofort für alle Produktionsprojekte gleichzeitig zu aktivieren.

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 der vorhandene, jedoch mit der Ergänzung von external_key_id in der API-Antwort.

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
}

War dieser Artikel hilfreich?