Santrauka
Prieiga
EKM endpoints pasiekiami Management API naudojant Admin API Key. https://platform.openai.com/settings/organization/admin-keys (nenaudokite įprasto API rakto). Admin API raktai prieinami organizacijos savininkams.
Naudokite
api.external_keys.write, kad sukurtumėte arba ištrintumėte išorinius raktus, oapi.external_keys.read– kad išvardytumėte arba patikrintumėte išorinius raktus. Vienam raktui abiejų apimčių reikia tik tada, jei jis turi atlikti ir skaitymo, ir rašymo operacijas.Šiuo metu turime jūsų organizacijai įjungti šiuos endpoints per funkcijos vėliavėlę. Kad funkcijos vėliavėlė įjungta, suprasite, jei matysite external_key_id , grąžinamą iš esamo List Projects endpoint: https://api.openai.com/v1/organization/projects
Naudojimas
Jūsų EKM konfigūracija užregistruojama organizacijos lygmeniu per naują endpoint https://api.openai.com/v1/organization/external_keys
Užregistravus EKM konfigūraciją, grąžinamas external_key_id formatu extkey_xxxx
EKM konfigūracijos aktyvuojamos projekto lygmeniu, esamo Create Project endpoint https://api.openai.com/v1/organization/projects užklausos tekste perduodant external_key_id
Apribojimai
Pirmiausia turite išbandyti EKM naujame projekte naudodami Management API.
Rekomenduojame EKM darbo krūviams sukurti naujus projektus. Tačiau jei norite EKM esamame projekte, galime jums įjungti funkcijos vėliavėlę. Prieš diegdami EKM esamuose gamybiniuose projektuose, atkreipkite dėmesį į šias gerąsias praktikas.
Pirmiausia išbandykite visas gamyboje naudojamas API funkcijas bandomajame EKM API projekte
Diekite palaipsniui, o ne įjunkite EKM visuose gamybiniuose API projektuose iš karto
Organizacijos lygmens endpoints
Užregistruokite išorinį raktą savo organizacijoje
AWS
Užklausos pavyzdys
type: string - visada „aws“
name: string - Patogus jūsų konfigūracijos pavadinimas
role_arn: string - Vaidmens ARN, kurį OpenAI perims jūsų debesijoje
kms_arn: string - Jūsų valdomo pagrindinio rakto Key Management System ARN
external_id: string - Jūsų organizacijos ID arba API projekto ID
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>
}'Atsakymo pavyzdys
{
"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
Užklausos pavyzdys
type: string - visada "gcp",
name: string - Patogus jūsų konfigūracijos pavadinimas
workload_identity_project_number: string - 12 skaitmenų GCP projekto numeris, kuriame užregistravote OpenAI darbo krūvio tapatybę
workload_identity_pool_id: string - Telkinys, kuriame yra OpenAI užregistruotas Workload Identity teikėjas
workload_identity_provider_id: string - Workload Identity teikėjas, kurį užregistravote OpenAI
audience: string - Auditorija, kurią OpenAI turėtų perduoti žetone, kai per jūsų GCP STS perimame vaidmenį
kms_project_id: string - GCP projekto, kuriame yra jūsų KMS, pavadinimas
kms_key_ring_name: string - Key Management System raktų žiedas, kuriame yra jūsų valdomas pagrindinis raktas
kms_key_name: string - Key Management System pagrindinio rakto pavadinimas
kms_key_location: string - Regionas, kuriame yra jūsų Key Management System pagrindinis raktas
Jei jūsų KMS yra kitame GCP projekte nei tas, kuriame užregistravote OpenAI Workload Identity, įsitikinkite, kad projekte su OpenAI Workload Identity bent jau įjungtas KMS, apsilankę 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"
}'Atsakymo pavyzdys
{
"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
Užklausos pavyzdys
type: string - visada "azure",
name: string - Patogus jūsų konfigūracijos pavadinimas
tenant_id: string - Jūsų Azure nuomotojo UUID
vault_uri: string - Azure saugyklos, kurioje yra jūsų valdomas pagrindinis raktas, URI
key_name: string - Jūsų valdomo Azure Key Vault pagrindinio rakto pavadinimas.
Jis turi būti formos <org-xxx>--<any_name>
kur org-xxx yra jūsų OpenAI organizacijos ID, kurį rasite adresu 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"
}'Atsakymo pavyzdys
{
"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"
}Ištrinkite jūsų organizacijoje užregistruotą išorinį raktą
Pastaba. Išorinį raktą galite ištrinti tik tada, jei jis nesusietas su jokiais aktyviais API projektais ar darbo erdve. Jei jis susietas su aktyviu API projektu, pirmiausia archyvuokite tą projektą. Jei jis susietas su darbo erdve, rakto ištrinti negalima.
Užklausos pavyzdys
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Atsakymo pavyzdys
{
"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>"
}Gaukite jūsų organizacijoje užregistruotus išorinius raktus
Užklausos pavyzdys
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Atsakymo pavyzdys
{
"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"
}Patikrinkite išorinį raktą
Šį endpoint galite naudoti keliems dalykams patikrinti
Ar jūsų išorinė debesijos konfigūracija po atliktų pakeitimų vis dar galioja su OpenAI (matysite sėkmingą atsakymą)
Ar rakto atšaukimas atliktas tinkamai, yra apdorojamas OpenAI ir įsigalios pasibaigus 1 valandos talpyklos TTL (matysite klaidos atsakymą)
Užklausos pavyzdys
curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Atsakymo pavyzdys
{
"status": "success"
}Arba iš debesijos paslaugų teikėjo gauta klaida.
Projekto lygmens endpoints
Sukurkite naują projektą naudodami išorinio rakto ID
Tai tas pats kaip esamas Create Project endpoint, tik užklausoje ir atsakyme papildomai pateikiamas parametras external_key_id.
Užklausos pavyzdys
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"
}'Atsakymo pavyzdys
{
"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,
}[Apribota] Atnaujinkite esamą projektą naudodami išorinio rakto ID
Tai tas pats kaip esamas Update Project endpoint, tik užklausoje ir atsakyme papildomai pateikiamas parametras external_key_id.
Rekomenduojame EKM darbo krūviams sukurti naujus API projektus. Jei norite EKM visuose esamuose API projektuose, kreipkitės į savo paskyros direktorių, ir mes įjungsime jums funkcijos vėliavėlę. Prieš diegdami EKM esamuose gamybiniuose projektuose, atkreipkite dėmesį į šias gerąsias praktikas.
Pirmiausia išbandykite visas gamyboje naudojamas API funkcijas bandomajame EKM API projekte
Diekite palaipsniui, o ne įjunkite EKM visuose gamybiniuose API projektuose iš karto
Užklausos pavyzdys
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"
}'Išvardykite visus savo organizacijos projektus
Tai tas pats kaip esamas endpoint, tik API atsakyme papildomai pateikiamas external_key_id
Užklausos pavyzdys
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Atsakymo pavyzdys
{
"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
}