Rezumat
Acces
Endpointurile EKM sunt accesibile în API-ul de management printr-o cheie API de administrator. https://platform.openai.com/settings/organization/admin-keys (nu folosiți o cheie API obișnuită). Cheile API de administrator sunt disponibile pentru proprietarii organizației.
Folosiți
api.external_keys.writepentru a crea sau șterge chei externe șiapi.external_keys.readpentru a lista sau valida chei externe. O singură cheie are nevoie de ambele domenii de acces doar dacă trebuie să efectueze atât operațiuni de citire, cât și de scriere.În prezent, trebuie să activăm un feature flag pentru organizația dvs. ca să acceseze aceste endpointuri. Știți că aveți feature flag-ul dacă vedeți external_key_id returnat de endpointul existent List Projects: https://api.openai.com/v1/organization/projects
Utilizare
Configurația dvs. EKM este înregistrată la nivel de organizație printr-un endpoint nou https://api.openai.com/v1/organization/external_keys
Înregistrarea configurației 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 endpointului existent Create Project https://api.openai.com/v1/organization/projects
Restricții
Trebuie să testați mai întâi EKM pe un proiect nou prin API-ul de management.
Recomandăm crearea de proiecte noi pentru sarcinile dvs. de lucru EKM. Totuși, dacă doriți EKM într-un proiect existent, vă putem adăuga la feature flag. Rețineți următoarele bune practici înainte de a implementa EKM în proiectele dvs. de producție existente.
Testați mai întâi toate funcționalitățile API pe care le folosiți în producție în proiectul dvs. API EKM de test
Aplicați o lansare treptată în loc să activați EKM 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 solicitare
type: string - întotdeauna „aws”
name: string - Un nume ușor de recunoscut pentru configurația dvs.
role_arn: string - ARN-ul rolului pe care OpenAI îl va asuma în cloudul dvs.
kms_arn: string - ARN-ul Key Management System pentru cheia principală pe care o gestionați
external_id: string - ID-ul organizației dvs. 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 solicitare
type: string - întotdeauna "gcp",
name: string - Un nume ușor de recunoscut pentru configurația dvs.
workload_identity_project_number: string - Numărul de proiect GCP din 12 cifre unde ați înregistrat identitatea de workload a OpenAI
workload_identity_pool_id: string - Pool-ul care conține furnizorul Workload Identity pe care l-ați înregistrat pentru OpenAI
workload_identity_provider_id: string - Furnizorul Workload Identity pe care l-ați înregistrat pentru OpenAI
audience: string - Audiența pe care OpenAI trebuie să o transmită în token atunci când asumăm un rol prin GCP STS-ul dvs.
kms_project_id: string - Numele proiectului GCP unde se află KMS-ul dvs.
kms_key_ring_name: string - Inelul de chei Key Management System care conține cheia principală pe care o gestionați
kms_key_name: string - Numele cheii principale Key Management System
kms_key_location: string - Regiunea unde se află cheia principală Key Management System
Dacă KMS-ul dvs. se află într-un alt proiect GCP decât cel în care ați înregistrat Workload Identity a OpenAI, asigurați-vă că proiectul care conține 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 solicitare
type: string - întotdeauna "azure",
name: string - Un nume ușor de recunoscut pentru configurația dvs.
tenant_id: string - UUID-ul tenantului Azure
vault_uri: string - URI-ul seifului Azure care conține cheia principală pe care o gestionați
key_name: string - Numele cheii principale Azure Key Vault pe care o gestionați.
Trebuie să aibă forma <org-xxx>--<any_name>
unde org-xxx este ID-ul organizației OpenAI, pe care îl puteț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ți o cheie externă înregistrată în organizația dvs.
Notă: Puteți șterge o cheie externă doar dacă nu este asociată cu niciun proiect API activ sau spațiu de lucru. Dacă este asociată cu un proiect API activ, arhivați mai întâi proiectul respectiv. Dacă este asociată cu un spațiu de lucru, cheia nu poate fi ștearsă.
Exemplu de solicitare
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ți cheile externe înregistrate în organizația dvs.
Exemplu de solicitare
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"
}Validați o cheie externă
Puteți folosi acest endpoint pentru a verifica mai multe lucruri
Configurația dvs. externă de cloud rămâne validă cu OpenAI după ce ați făcut modificări (veți vedea un răspuns de succes)
Revocarea cheii a fost efectuată corect, este procesată de OpenAI și va intra în vigoare după expirarea TTL-urilor cache de 1 oră (veți vedea un răspuns de eroare)
Exemplu de solicitare
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
Creați un proiect nou cu un ID de cheie externă
Este același cu endpointul existent Create Project, dar cu adăugarea parametrului external_key_id în solicitare și răspuns.
Exemplu de solicitare
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": "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,
}[Restricționat] Actualizați un proiect existent cu un ID de cheie externă
Este același cu endpointul existent Update Project, dar cu adăugarea parametrului external_key_id în solicitare și răspuns.
Recomandăm crearea de proiecte API noi pentru sarcinile dvs. de lucru EKM. Dacă doriți EKM pentru toate proiectele API existente, solicitați directorului dvs. de cont, iar noi vă vom adăuga la feature flag. Rețineți următoarele bune practici înainte de a implementa EKM în proiectele dvs. de producție existente.
Testați mai întâi toate funcționalitățile API pe care le folosiți în producție în proiectul dvs. API EKM de test
Aplicați o lansare treptată în loc să activați EKM simultan în toate proiectele API de producție
Exemplu de solicitare
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"
}'Listați toate proiectele din organizația dvs.
Este același cu endpointul existent, dar cu adăugarea external_key_id în răspunsul API
Exemplu de solicitare
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
}