Összefoglaló
Hozzáférés
Az EKM-végpontok a Management API-n keresztül, adminisztrátori API-kulccsal érhetők el. https://platform.openai.com/settings/organization/admin-keys (ne használj normál API-kulcsot). Az adminisztrátori API-kulcsok a szervezet tulajdonosai számára érhetők el.
Külső kulcsok létrehozásához vagy törléséhez használd az
api.external_keys.write, listázásukhoz, lekérésükhöz vagy ellenőrzésükhöz pedig azapi.external_keys.readjogosultsági hatókört. Egy kulcsnak csak akkor van szüksége mindkét hatókörre, ha olvasási és írási műveleteket is kell végeznie.
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
Az EKM-et először egy új projektben kell tesztelned a Management API-n keresztül.
Javasoljuk, hogy az EKM-et igénylő feladatokhoz hozz létre új projekteket. 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-tesztelésre szolgáló API-projektedben teszteld az éles környezetben használt összes API-funkciót.
Fokozatosan vezesd be az EKM-et, ne egyszerre állítsd be 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"
}OCI
Állíts be egy engedélyezett AES-256-kulcsot, és adj hozzáférést az OpenAI számára. A kulcshoz egy szabad formátumú openai_organization_id címkét kell rendelni, amelynek értéke az OpenAI-szervezetazonosítód. A beállítás lépéseit itt találod: Az OCI Vault konfigurálása vállalati kulcskezeléshez.
Példakérés:
type: karakterlánc – mindig "oci"
purpose: karakterlánc – "ekm"; ha nincs megadva, ez az alapértelmezett érték
name: karakterlánc – A konfiguráció könnyen azonosítható neve
region: karakterlánc – A tárolót és a kulcsot tartalmazó OCI-régió
vault_ocid: karakterlánc – A tároló teljes OCID-je
key_ocid: karakterlánc – Az AES-256-kulcs teljes OCID-je
EKM esetén ne add meg a key_version_ocid paramétert.
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>"
}'Példaválasz:
{
"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>"
}Siker esetén az API HTTP 200-as állapotkódot ad vissza. Mentsd el a visszakapott id értéket, és projekt létrehozásakor ezt add meg az external_key_id értékeként. A meglévő listázási, lekérési, ellenőrzési és törlési műveletek az OCI-regisztrációkra is alkalmazhatók.
PSP-helyreállításhoz használj külön RSA-3072-regisztrációt purpose: "psp_decryption" beállítással és egy pontos key_version_ocid értékkel. A psp_decryption_key_id értékét állítsd ennek OpenAI-regisztrációs azonosítójára. Az OpenAI számára elegendő olvasási hozzáférést biztosítani az adott RSA-kulcs metaadataihoz és nyilvános kulcsaihoz. A teljes beállítási útmutatót itt találod: Aszimmetrikus kulcsok beállítása – OCI Vault.
A szervezetednél regisztrált külső kulcs törlése
Megjegyzés: A törlés nem engedélyezett, amíg egy aktív projekt vagy munkaterület használja a regisztrációt. EKM esetén először archiváld a kapcsolódó API-projekteket; a munkaterülethez kapcsolódó EKM-regisztráció továbbra is védett marad. PSP-helyreállítás esetén a regisztráció törlése előtt módosítsd vagy töröld a psp_decryption_key_id értékét minden olyan aktív projektben, amely a regisztrációra hivatkozik. Az OpenAI-regisztráció törlése nem törli a felhőben tárolt kulcsot.
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 szervezetednél regisztrált külső kulcsok lekérése
Felhasználási cél szerinti szűrés nélkül a lista az EKM- és a PSP-helyreállítási regisztrációkat is tartalmazza. Használd a ?purpose=ekm vagy a ?purpose=psp_decryption paramétert a felhasználási cél szerinti szűréshez.
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
Az ellenőrzéssel meggyőződhetsz arról, hogy az OpenAI továbbra is hozzáfér-e a felhőben tárolt kulcsodhoz.
EKM esetén az OpenAI ellenőrzi, hogy képes-e titkosítani és visszafejteni a kulccsal. A visszavonás és a gyorsítótárazás működését a kulcsok életciklusáról szóló útmutató ismerteti.
PSP-helyreállítás esetén az OpenAI lekéri a regisztrált verzió nyilvános kulcsát, és összehasonlítja a tárolt pillanatképpel. A sikeres ellenőrzés nem igazolja, hogy a helyreállításhoz használt identitásod képes a visszafejtésre. A sikertelen ellenőrzés nem távolítja el és nem cseréli le a nyilvános kulcs tárolt pillanatképét.
A regisztráció GET-tel történő lekérése a tárolt konfigurációt adja vissza, és nem ellenőrzi újra a felhőben tárolt kulcsodhoz való hozzáférést.
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"
}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 igénylő feladatokhoz hozz létre új API-projekteket. 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-tesztelésre szolgáló API-projektedben teszteld az éles környezetben használt összes API-funkciót.
Fokozatosan vezesd be az EKM-et, ne egyszerre állítsd be 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
}