Rezumat
Acces
Punctele finale EKM sunt accesibile în API-ul de administrare printr-o cheie API de administrator. https://platform.openai.com/settings/organization/admin-keys (nu folosi o cheie API obișnuită). Cheile API de administrator sunt disponibile pentru proprietarii organizației.
Folosește
api.external_keys.writepentru a crea sau a șterge chei externe șiapi.external_keys.readpentru a lista, a prelua sau a valida chei externe. O cheie are nevoie de ambele permisiuni doar dacă trebuie să efectueze atât operațiuni de citire, cât și de scriere.
Utilizare
Configurația ta EKM este înregistrată la nivel de organizație printr-un nou punct final: https://api.openai.com/v1/organization/external_keys.
Înregistrarea configurației tale EKM returnează un external_key_id de forma extkey_xxxx.
Configurațiile EKM sunt activate la nivel de proiect prin transmiterea unui external_key_id în corpul cererii către punctul final existent pentru crearea unui proiect: https://api.openai.com/v1/organization/projects.
Restricții
Trebuie să testezi mai întâi EKM într-un proiect nou, prin API-ul de administrare.
Recomandăm crearea unor proiecte noi pentru sarcinile tale de lucru EKM. Ține cont de următoarele bune practici înainte de a implementa EKM în proiectele tale existente din producție.
Testează mai întâi toate funcționalitățile API pe care le folosești în producție în proiectul tău API de testare cu EKM.
Implementează EKM treptat, în loc să îl activezi simultan în toate proiectele API din producție.
Endpointuri la nivel de organizație
Înregistrați o cheie externă în organizația dvs.
AWS
Exemplu de cerere:
type: șir de caractere - întotdeauna „aws”
name: șir de caractere - Un nume ușor de recunoscut pentru configurația ta
role_arn: șir de caractere - ARN-ul rolului pe care OpenAI îl va asuma în mediul tău cloud
kms_arn: șir de caractere - ARN-ul din sistemul de gestionare a cheilor pentru cheia principală pe care o gestionezi
external_id: șir de caractere - ID-ul de organizație sau ID-ul proiectului API
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>"
}'Exemplu de răspuns:
{
"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
Exemplu de cerere:
type: șir de caractere - întotdeauna „gcp”,
name: șir de caractere - Un nume ușor de recunoscut pentru configurația ta
workload_identity_project_number: șir de caractere - Numărul proiectului GCP în care ai înregistrat identitatea sarcinii de lucru OpenAI
workload_identity_pool_id: șir de caractere - Grupul care conține furnizorul Workload Identity înregistrat pentru OpenAI
workload_identity_provider_id: șir de caractere - Furnizorul Workload Identity înregistrat pentru OpenAI
audience: șir de caractere - Destinatarul pe care OpenAI trebuie să îl includă în token atunci când ne asumăm un rol prin serviciul tău GCP STS
kms_project_id: șir de caractere - Numele proiectului GCP care găzduiește sistemul tău KMS
kms_key_ring_name: șir de caractere - Setul de chei din sistemul de gestionare a cheilor care conține cheia principală pe care o gestionezi
kms_key_name: șir de caractere - Numele cheii principale din sistemul de gestionare a cheilor
kms_key_location: șir de caractere - Regiunea în care se află cheia principală din sistemul de gestionare a cheilor
Dacă sistemul tău KMS este găzduit într-un alt proiect GCP decât cel în care ai înregistrat identitatea Workload Identity a OpenAI, asigură-te că proiectul care conține identitatea Workload Identity a OpenAI are cel puțin KMS activat, accesând 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"
}'Exemplu de răspuns:
{
"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
Exemplu de cerere:
type: șir de caractere - întotdeauna „azure”,
name: șir de caractere - Un nume ușor de recunoscut pentru configurația ta
tenant_id: șir de caractere - UUID-ul entității tale găzduite Azure
vault_uri: șir de caractere - URI-ul seifului Azure care conține cheia principală pe care o gestionezi
key_name: șir de caractere - Numele cheii principale din Azure Key Vault pe care o gestionezi.
Trebuie să aibă forma <org-xxx>--<any_name>
unde org-xxx este ID-ul tău de organizație OpenAI, pe care îl poți găsi la 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"
}'Exemplu de răspuns:
{
"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
Configurează o cheie AES-256 activată și acordă acces companiei OpenAI. Cheia trebuie să aibă o etichetă în format liber openai_organization_id, setată la ID-ul organizației tale OpenAI. Pentru pașii de configurare, consultă: Configurarea OCI Vault pentru gestionarea cheilor la nivel de întreprindere.
Exemplu de cerere:
type: string – întotdeauna "oci"
purpose: string – "ekm"; valoarea implicită dacă parametrul este omis
name: string – Un nume ușor de recunoscut pentru configurația ta
region: string – Regiunea OCI în care se află seiful și cheia
vault_ocid: string – OCID-ul complet al seifului
key_ocid: string – OCID-ul complet al cheii AES-256
Nu transmite key_version_ocid pentru EKM.
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>"
}'Exemplu de răspuns:
{
"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>"
}API-ul returnează HTTP 200 dacă operațiunea reușește. Salvează valoarea id returnată și folosește-o ca external_key_id când creezi un proiect. Operațiunile existente de listare, preluare, validare și ștergere se aplică și înregistrărilor OCI.
Pentru recuperarea PSP, folosește o înregistrare RSA-3072 separată, cu purpose: "psp_decryption" și o valoare exactă pentru key_version_ocid. Setează psp_decryption_key_id la ID-ul înregistrării sale în OpenAI. OpenAI are nevoie doar de acces de citire la metadatele și cheile publice ale acelei chei RSA. Pentru configurarea completă, consultă: Configurarea cheilor asimetrice — OCI Vault.
Șterge o cheie externă înregistrată în organizația ta
Notă: Ștergerea este blocată cât timp un proiect sau un spațiu de lucru activ folosește înregistrarea. Pentru EKM, arhivează mai întâi proiectele API asociate; o înregistrare EKM asociată unui spațiu de lucru rămâne protejată. Pentru recuperarea PSP, înlocuiește sau golește valoarea psp_decryption_key_id în fiecare proiect activ care face referire la înregistrare, înainte de a o șterge. Ștergerea unei înregistrări OpenAI nu șterge cheia din cloud.
Exemplu de cerere
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Exemplu de răspuns
{
"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>"
}Obține cheile externe înregistrate în organizația ta
Fără un filtru după scop, lista include atât înregistrările EKM, cât și pe cele pentru recuperare PSP. Folosește ?purpose=ekm sau ?purpose=psp_decryption pentru a filtra după scop.
Exemplu de cerere
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Exemplu de răspuns
{
"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"
}Validează o cheie externă
Folosește validarea pentru a verifica dacă OpenAI îți poate accesa în continuare cheia din cloud.
Pentru EKM, OpenAI verifică dacă poate cripta și decripta cu ajutorul cheii. Pentru detalii despre revocare și stocarea în cache, consultă: îndrumările privind ciclul de viață al cheilor.
Pentru recuperarea PSP, OpenAI preia cheia publică a versiunii înregistrate și o compară cu copia stocată. Validarea reușită nu confirmă că identitatea ta de recuperare poate efectua decriptarea. Validarea eșuată nu elimină și nu înlocuiește copia stocată a cheii publice.
Preluarea unei înregistrări prin GET returnează configurația stocată și nu verifică din nou accesul la cheia ta din cloud.
Exemplu de cerere
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Exemplu de răspuns
{
"status": "success"
}Sau o eroare transmisă de furnizorul de cloud.
Endpointuri la nivel de proiect
Creează un proiect nou cu un ID de cheie externă
Acest punct final este identic cu cel existent pentru crearea unui proiect, dar include și parametrul external_key_id în cerere și în răspuns.
Exemplu de cerere
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"
}'Exemplu de răspuns
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Actualizează un proiect existent cu ID-ul unei chei externe
Acesta este identic cu punctul final existent pentru actualizarea proiectelor, cu adăugarea parametrului external_key_id în cerere și în răspuns.
Recomandăm crearea unor proiecte API noi pentru sarcinile tale de lucru EKM. Ține cont de următoarele bune practici înainte de a implementa EKM în proiectele tale existente din producție.
Testează mai întâi toate funcționalitățile API pe care le folosești în producție în proiectul tău API de testare cu EKM.
Implementează EKM treptat, în loc să îl activezi simultan în toate proiectele API din producție.
Exemplu de cerere
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"
}'Listează toate proiectele din organizația ta
Acest punct final este identic cu cel existent, dar include și external_key_id în răspunsul API.
Exemplu de cerere
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Exemplu de răspuns
{
"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
}