Összefoglalás

Hozzáférés

• Az EKM-végpontok a Management API-ban egy Admin API Key használatával érhetők el. https://platform.openai.com/settings/organization/admin-keys (ne használjon normál API-kulcsot). Az Admin API-kulcsok a szervezet tulajdonosai számára érhetők el.

• A külső kulcsok létrehozásához vagy törléséhez használja a api.external_keys.write, a külső kulcsok listázásához vagy ellenőrzéséhez pedig a api.external_keys.read jogosultságot. Egyetlen kulcsnak csak akkor van szüksége mindkét hatókörre, ha olvasási és írási műveleteket is kell végeznie.

• Jelenleg külön feature flaggel kell engedélyeznünk ezeket a végpontokat az Ön szervezeténél. Akkor tudhatja, hogy rendelkezik ezzel a feature flaggel, ha a meglévő List Projects végpontból visszakapja az **external_key_id ** értéket: https://api.openai.com/v1/organization/projects

Használat

• Az Ön EKM-konfigurációja regisztrálva van szervezeti szinten egy új végponton keresztül: https://api.openai.com/v1/organization/external_keys

• Az EKM-konfiguráció regisztrálása egy extkey_xxxx formátumú external_key_id értéket ad vissza

• Az EKM-konfigurációk aktiválása projektszinten történik úgy, hogy megad egy external_key_id értéket a meglévő Create Project https://api.openai.com/v1/organization/projects végpont törzsében

Korlátozások

• Először egy új projekten kell tesztelnie az EKM-et a Management API-n keresztül.

• Javasoljuk, hogy hozzon létre új projekteket az EKM-munkaterheléseihez. Ha azonban egy meglévő projekten szeretné használni az EKM-et, hozzáadhatjuk a feature flaghez. Kérjük, vegye figyelembe az alábbi ajánlott gyakorlatokat, mielőtt bevezeti az EKM-et a meglévő éles projektjeiben.

  • Először az EKM-teszt API-projektjében tesztelje az összes olyan API-funkciót, amelyet éles környezetben használ

  • Fokozatos bevezetést alkalmazzon ahelyett, hogy egyszerre töltené fel EKM-mel az összes éles API-projektet

Szervezeti szintű végpontok

Külső kulcs regisztrálása a szervezetén

AWS

Példakérés

• type: string - mindig „aws”

• name: string - A konfiguráció rövid, könnyen azonosítható neve

• role_arn: string - Az a Role ARN, amelyet az OpenAI felvesz a felhőkörnyezetében

• kms_arn: string - Az Ön által kezelt főkulcshoz tartozó Key Management System ARN

• external_id: string - Az Ön szervezeti azonosítója vagy API-projektazonosítója

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

Példaválasz

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

Példakérés

• type: string - mindig "gcp",

• name: string - A konfiguráció rövid, könnyen azonosítható neve

• workload_identity_project_number: string - Annak a GCP-projektnek a 12 számjegyű projektszáma, ahol regisztrálta az OpenAI workload identityját

• workload_identity_pool_id: string - Az a pool, amely tartalmazza az OpenAI számára regisztrált Workload Identity providert

• workload_identity_provider_id: string - Az OpenAI számára regisztrált Workload Identity provider

• audience: string - Az audience érték, amelyet az OpenAI-nak át kell adnia a tokenben, amikor szerepet vesz fel az Ön GCP STS-én keresztül

• kms_project_id: string - Annak a GCP-projektnek a neve, ahol a KMS található

• kms_key_ring_name: string - Az Ön által kezelt főkulcsot tartalmazó Key Management System kulcsgyűrű

• kms_key_name: string - A Key Management System főkulcs neve

• kms_key_location: string - Az a régió, ahol a Key Management System főkulcs található

Ha az Ön KMS-e másik GCP-projektben található, mint ahol az OpenAI Workload Identityját regisztrálta, győződjön meg arról, hogy legalább a projekt, amely az OpenAI Workload Identityját tartalmazza, engedélyezve van a KMS-hez, ehhez látogasson el ide: https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview

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

Példaválasz

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

Példakérés

• type: string - mindig "azure",

• name: string - A konfiguráció rövid, könnyen azonosítható neve

• tenant_id: string - Az Ön Azure-bérlőjének UUID-je

• vault_uri: string - Az Ön által kezelt főkulcsot tartalmazó Azure vault URI-ja

• key_name: string - Az Ön által kezelt Azure Key Vault főkulcs neve.

  • A formátuma <org-xxx>--<any_name> kell legyen

  • ahol az org-xxx az Ön OpenAI szervezeti azonosítója, amely itt található: https://platform.openai.com/settings/organization/general

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

Példaválasz

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

A szervezetén regisztrált külső kulcs törlése

Megjegyzés: Külső kulcsot csak akkor törölhet, ha az nincs egyetlen aktív projekthez sem társítva. Ha aktív projekthez van társítva, először archiválnia kell azt a projektet.

Példakérés

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"

Példaválasz

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

A szervezetén regisztrált külső kulcsok lekérése

Példakérés

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"

Példaválasz

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

Külső kulcs ellenőrzése

Ezzel a végponttal több dolgot is ellenőrizhet

• Az Ön külső felhőkonfigurációja az OpenAI-nál a módosítások után is érvényes marad (sikeres választ fog látni)

• A kulcs visszavonása helyesen történt, az OpenAI feldolgozza, és az 1 órás gyorsítótár-TTL-ek lejárta után lép életbe (hibaüzenetet fog látni)

Példakérés

curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

Példaválasz

{
 "status": "success"
}

Vagy a felhőszolgáltatótól származó hiba jelenik meg.

Projektszintű végpontok

Új projekt létrehozása külső kulcs azonosítójával

Ez megegyezik a meglévő Create Project végponttal, azzal a kiegészítéssel, hogy a kérésben és a válaszban szerepel az external_key_id paraméter.

Példakérés

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

Példaválasz

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

[Korlátozott] Meglévő projekt frissítése külső kulcs azonosítójával

Ez megegyezik a meglévő Update Project végponttal, azzal a kiegészítéssel, hogy a kérésben és a válaszban szerepel az external_key_id paraméter.

Javasoljuk, hogy hozzon létre új API-projekteket az EKM-munkaterheléseihez. Ha az összes meglévő API-projektjén szeretné használni az EKM-et, forduljon account directorjához, és hozzáadjuk a feature flaghez. Kérjük, vegye figyelembe az alábbi ajánlott gyakorlatokat, mielőtt bevezeti az EKM-et a meglévő éles projektjeiben.

• Először az EKM-teszt API-projektjében tesztelje az összes olyan API-funkciót, amelyet éles környezetben használ

• Fokozatos bevezetést alkalmazzon ahelyett, hogy egyszerre töltené fel EKM-mel az összes éles API-projektet

Példakérés

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

A szervezet összes projektjének listázása

Ez megegyezik a meglévő végponttal, de az API-válasz kiegészül az external_key_id mezővel

Példakérés

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"

Példaválasz

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