Rezumat
Acces
Punctele finale EKM sunt accesibile în API-ul de gestionare folosind 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 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.În prezent, trebuie să activăm accesul organizației tale la aceste puncte finale printr-un indicator de funcționalitate. Poți verifica dacă indicatorul de funcționalitate este activat căutând external_key_id în răspunsul returnat de punctul final existent pentru listarea proiectelor: https://api.openai.com/v1/organization/projects.
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 gestionare.
Recomandăm crearea unor proiecte noi pentru sarcinile tale de lucru EKM. Totuși, dacă vrei EKM pentru un proiect existent, îți putem activa accesul prin indicatorul de funcționalitate. Ține cont de următoarele bune practici înainte de a implementa EKM în proiectele tale de producție existente.
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 de 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"
}Șterge o cheie externă înregistrată în organizația ta
Notă: Poți șterge o cheie externă doar dacă nu este asociată cu niciun proiect API activ și cu niciun spațiu de lucru. Dacă este asociată cu un proiect API activ, arhivează mai întâi proiectul respectiv. Dacă este asociată cu un spațiu de lucru, cheia nu poate fi ștearsă.
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
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ă
Poți folosi acest punct final pentru a verifica mai multe aspecte:
Configurația ta cloud externă rămâne validă pentru OpenAI după ce ai făcut modificări (vei primi un răspuns de succes).
Revocarea cheii a fost efectuată corect, este în curs de procesare de către OpenAI și va intra în vigoare după expirarea perioadelor TTL de o oră ale memoriei cache (vei primi un răspuns de eroare).
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"
}[Acces restricționat] Actualizează un proiect existent cu un ID de cheie externă
Acest punct final este identic cu cel existent pentru actualizarea unui proiect, dar include și parametrul external_key_id în cerere și în răspuns.
Recomandăm crearea unor proiecte API noi pentru sarcinile tale de lucru EKM. Dacă vrei EKM pentru toate proiectele tale API existente, contactează directorul tău de cont și îți vom activa accesul prin indicatorul de funcționalitate. Ține cont de următoarele bune practici înainte de a implementa EKM în proiectele tale de producție existente.
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 de 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
}