Összefoglaló

Hozzáférés

Az EKM-végpontok a felügyeleti API-ban érhetők el egy adminisztrátori API-kulccsal. https://platform.openai.com/settings/organization/admin-keys (ne használj normál API-kulcsot). Az adminisztrátori API-kulcsok a szervezettulajdonosok számára érhetők el.
Külső kulcsok létrehozásához vagy törléséhez az api.external_keys.write, listázásához vagy érvényesítéséhez pedig az api.external_keys.read jogosultsági hatókört használd. Egy kulcsnak csak akkor van szüksége mindkét hatókörre, ha olvasási és írási műveleteket is végre kell hajtania.
Jelenleg egy funkciókapcsolóval kell engedélyeznünk a szervezeted hozzáférését ezekhez a végpontokhoz. A funkciókapcsoló akkor van engedélyezve, ha a meglévő projektlistázási végpont válaszában megjelenik az external_key_id: https://api.openai.com/v1/organization/projects.

Használat

Az EKM-konfiguráció regisztrálása szervezeti szinten történik egy új végponton keresztül: https://api.openai.com/v1/organization/external_keys.
Az EKM-konfiguráció regisztrálásakor egy extkey_xxxx formátumú external_key_id azonosítót kapsz.
Az EKM-konfigurációk aktiválása projektszinten történik: ehhez egy external_key_id azonosítót kell megadni a meglévő projektlétrehozási végpontra küldött kérés törzsében: https://api.openai.com/v1/organization/projects.

Korlátozások

Először egy új projektben kell tesztelned az EKM-et a felügyeleti API-n keresztül.
Javasoljuk, hogy az EKM-et használó feladatokhoz hozz létre új projekteket. Ha azonban egy meglévő projektben szeretnél EKM-et használni, engedélyezhetjük számodra a funkciókapcsolót. Mielőtt bevezetnéd az EKM-et a meglévő éles projektjeidben, vedd figyelembe az alábbi bevált gyakorlatokat.
- Először az EKM-es teszt-API-projektedben tesztelj minden olyan API-funkciót, amelyet éles környezetben használsz.
- Fokozatosan vezesd be az EKM-et, ne egyszerre engedélyezd az összes éles API-projektben.

Szervezetszintű endpoints

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

AWS

Példakérés:

type: karakterlánc – mindig „aws”
name: karakterlánc – A konfiguráció könnyen felismerhető neve
role_arn: karakterlánc – Annak a szerepkörnek az ARN-je, amelyet az OpenAI a felhőkörnyezetedben felvesz
kms_arn: karakterlánc – Az általad kezelt főkulcs ARN-je a kulcskezelő rendszerben
external_id: karakterlánc – A szervezetazonosítód vagy az API-projekted azonosí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: karakterlánc – mindig „gcp”,
name: karakterlánc – A konfiguráció könnyen felismerhető neve
workload_identity_project_number: karakterlánc – Annak a GCP-projektnek a numerikus projektszáma, amelyben regisztráltad az OpenAI munkaterhelés-identitását
workload_identity_pool_id: karakterlánc – Az OpenAI számára regisztrált Workload Identity-szolgáltatót tartalmazó készlet
workload_identity_provider_id: karakterlánc – Az OpenAI számára regisztrált Workload Identity-szolgáltató
audience: karakterlánc – Az a célközönség, amelyet az OpenAI-nak a tokenben kell megadnia, amikor a GCP STS-szolgáltatásodon keresztül veszünk fel egy szerepkört
kms_project_id: karakterlánc – Annak a GCP-projektnek a neve, amelyben a KMS-ed található
kms_key_ring_name: karakterlánc – A kulcskezelő rendszer azon kulcskarikája, amely az általad kezelt főkulcsot tartalmazza
kms_key_name: karakterlánc – A kulcskezelő rendszer főkulcsának neve
kms_key_location: karakterlánc – Az a régió, amelyben a kulcskezelő rendszer főkulcsa található

Ha a KMS-ed másik GCP-projektben található, mint amelyben az OpenAI Workload Identity-identitását regisztráltad, győződj meg róla, hogy az OpenAI Workload Identity-identitását tartalmazó projektben legalább a KMS engedélyezve van. Ezt itt ellenőrizheted: 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: karakterlánc – mindig „azure”,
name: karakterlánc – A konfiguráció könnyen felismerhető neve
tenant_id: karakterlánc – Az Azure-bérlőd UUID-azonosítója
vault_uri: karakterlánc – Az általad kezelt főkulcsot tartalmazó Azure-kulcstartó URI-ja
key_name: karakterlánc – Az Azure Key Vaultban általad kezelt főkulcs neve.
- A következő formátumot kell követnie: <org-xxx>--<any_name>
- ahol az org-xxx az OpenAI-szervezetazonosítód, amelyet itt találsz: 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 szervezetedben regisztrált külső kulcs törlése

Megjegyzés: Külső kulcsot csak akkor törölhetsz, ha nincs aktív API-projekthez vagy munkaterülethez társítva. Ha aktív API-projekthez van társítva, először archiváld a projektet. Ha munkaterülethez van társítva, a kulcs nem törölhető.

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 szervezetedben 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 érvényesítése

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

A külső felhőkonfigurációd a módosítások után is érvényes az OpenAI számára (sikeres választ kapsz).
A kulcs visszavonása megfelelően történt, az OpenAI feldolgozza, és a gyorsítótárak 1 órás élettartamának (TTL) lejárta után érvénybe lép (hibaválaszt kapsz).

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ó által jelzett hiba.

Projektszintű endpoints

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

Ez megegyezik a meglévő projektlétrehozási végponttal, de a kérés és a válasz kiegészül az external_key_id paraméterrel.

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": "organization.project",
  "id": "proj_xxxxx",
  "name": "Some Project",
  "external_key_id": "extkey_xxxx",
  "created_at": 1740012721,
  "archived_at": null,
  "status": "active"
}

[Korlátozott hozzáférés] Meglévő projekt frissítése külső kulcsazonosítóval

Ez megegyezik a meglévő projektfrissítési végponttal, de a kérés és a válasz kiegészül az external_key_id paraméterrel.

Javasoljuk, hogy az EKM-et használó feladatokhoz hozz létre új API-projekteket. Ha minden meglévő API-projektedben szeretnél EKM-et használni, jelezd az ügyfélkapcsolati vezetődnek, és engedélyezzük számodra a funkciókapcsolót. Mielőtt bevezetnéd az EKM-et a meglévő éles projektjeidben, vedd figyelembe az alábbi bevált gyakorlatokat.

Először az EKM-es teszt-API-projektedben tesztelj minden olyan API-funkciót, amelyet éles környezetben használsz.
Fokozatosan vezesd be az EKM-et, ne egyszerre engedélyezd az összes éles API-projektben.

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
}

EKM (External Keys) a Management API-ban

Összefoglaló

Hozzáférés

Használat

Korlátozások

Szervezetszintű endpoints

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

AWS

GCP

Azure

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

Példakérés

Példaválasz

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

Példakérés

Példaválasz

Külső kulcs érvényesítése

Példakérés

Példaválasz

Projektszintű endpoints

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

Példakérés

Példaválasz

[Korlátozott hozzáférés] Meglévő projekt frissítése külső kulcsazonosítóval

Példakérés

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

Példakérés

Példaválasz

Hasznos volt ez a cikk?