Rezumat

Acces

• Punctele finale EKM sunt accesibile în Management API printr-o cheie API de administrator. https://platform.openai.com/settings/organization/admin-keys (nu folosiți o cheie API normală). Cheile API de administrator sunt disponibile pentru proprietarii organizației.

• Folosiți api.external_keys.write pentru a crea sau șterge chei externe și api.external_keys.read pentru a lista sau valida chei externe. O singură cheie are nevoie de ambele domenii de aplicare doar dacă trebuie să efectueze atât operațiuni de citire, cât și de scriere.

• În prezent, trebuie să activăm acest feature flag pentru organizația dvs. Știți că aveți feature flag-ul dacă vedeți **external_key_id **returnat de punctul final existent List Projects: https://api.openai.com/v1/organization/projects

Utilizare

• Configurația dvs. EKM este înregistrată la nivel de organizație printr-un nou punct final https://api.openai.com/v1/organization/external_keys

• Înregistrarea configurației dvs. EKM returnează un external_key_id în forma extkey_xxxx

• Configurațiile EKM sunt activate la nivel de proiect prin transmiterea unui external_key_id în corpul punctului final existent Create Project https://api.openai.com/v1/organization/projects

Restricții

• Mai întâi trebuie să testați EKM pe un proiect nou prin Management API.

• Recomandăm să creați proiecte noi pentru workload-urile dvs. EKM. Totuși, dacă doriți EKM pe 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 în proiectul dvs. de test EKM API toate funcțiile API pe care le folosiți în producție

  • Aplicați o lansare graduală în loc să populați EKM pe toate proiectele API de producție dintr-o dată

Puncte finale la nivel de organizație

Înregistrați o cheie externă în organizația dvs.

AWS

Exemplu de cerere

• 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 master 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": "Configurație AWS EKM",
  "role_arn": "arn:aws:iam::<12_DIGIT_ACCOUNT_NUMBER>:role/<ROLE>",
  "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  "external_id": <ID-ul organizației sau al proiectului dvs.>
}'

Exemplu de răspuns

{
  "id": "extkey_xxxx",
  "object": "organization.external_key",
  "created_at": 1746175499,
  "api_project_ids": [],
  "type": "aws",
  "name": "Configurație AWS EKM",
  "role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>",
  "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  "external_id": <ID-ul organizației sau al proiectului dvs.>
}  

GCP

Exemplu de cerere

• 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 în care 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 în care se află KMS-ul dvs.

• kms_key_ring_name: string - Inelul de chei Key Management System care conține cheia master pe care o gestionați

• kms_key_name: string - Numele cheii master Key Management System

• kms_key_location: string - Regiunea în care se află cheia master Key Management System

Dacă KMS-ul dvs. se află într-un proiect GCP diferit de cel în care ați înregistrat Workload Identity-ul OpenAI, asigurați-vă că proiectul care conține Workload Identity-ul 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": <ID-ul organizației sau al proiectului dvs.>,
   "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": "Configurație GCP EKM",
  "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": <ID-ul organizației sau al proiectului dvs.>,
  "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: string - întotdeauna "azure",

• name: string - Un nume ușor de recunoscut pentru configurația dvs.

• tenant_id: string - UUID-ul tenantului dvs. Azure

• vault_uri: string - URI-ul seifului Azure care conține cheia master pe care o gestionați

• key_name: string - Numele cheii master Azure Key Vault pe care o gestionați.

  • Trebuie să aibă forma <org-xxx>--<any_name>

  • unde org-xxx este ID-ul organizației dvs. 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": "Configurație Azure EKM",
  "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": "Configurație Azure EKM",
  "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 activ. Dacă este asociată cu un proiect activ, trebuie mai întâi să arhivați proiectul respectiv.

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": "Configurație AWS EKM",
  "role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}

Obțineți cheile externe înregistrate în organizația dvs.

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": "Configurație AWS EKM",
      "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 punct final pentru a verifica mai multe lucruri

• Configurația dvs. cloud externă rămâne validă cu OpenAI după ce ați făcut modificări (veți vedea un răspuns de succes)

• Revocarea cheii dvs. este făcută 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 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 provenită de la furnizorul de cloud.

Puncte finale la nivel de proiect

Creați un proiect nou cu un ID de cheie externă

Acesta este același lucru ca punctul final existent Create Project, cu adăugarea parametrului external_key_id în cerere și 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": "Un proiect oarecare",
   "external_key_id": "extkey_xxxx"
}'

Exemplu de răspuns

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Un proiect oarecare",
  "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ă

Acesta este același lucru ca punctul final existent Update Project, cu adăugarea parametrului external_key_id în cerere și răspuns.

Recomandăm să creați proiecte API noi pentru workload-urile dvs. EKM. Dacă doriți EKM pe toate proiectele dvs. API existente, cereți directorului dvs. de cont și 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 în proiectul dvs. de test EKM API toate funcțiile API pe care le folosiți în producție

• Aplicați o lansare graduală în loc să populați EKM pe toate proiectele API de producție dintr-o dată

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"
}'

Listați toate proiectele din organizația dvs.

Acesta este același lucru ca punctul final existent, dar cu adăugarea lui 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": "Nume proiect",
      "external_key_id": "extkey_xxxx",
      "created_at": 1717798982,
      "archived_at": null,
      "status": "active"
    }
  ],
  "first_id": "proj_xxxx",
  "last_id": "proj_xxxx",
  "has_more": true
}