Súhrn
Prístup
Endpoints EKM sú dostupné v rozhraní Management API pomocou Admin API Key. https://platform.openai.com/settings/organization/admin-keys (nepoužívajte bežný kľúč API). Správcovské kľúče API sú k dispozícii vlastníkom organizácie.
Použite
api.external_keys.writena vytváranie alebo odstraňovanie externých kľúčov aapi.external_keys.readna výpis alebo overenie externých kľúčov. Jeden kľúč potrebuje oba rozsahy oprávnení iba vtedy, ak musí vykonávať operácie čítania aj zápisu.Momentálne musíme vašej organizácii zapnúť prístup k týmto endpoints cez feature flag. Feature flag máte vtedy, keď sa vám z existujúceho endpoint List Projects vráti external_key_id : https://api.openai.com/v1/organization/projects
Použitie
Vaša konfigurácia EKM je zaregistrovaná na úrovni organizácie cez nový endpoint https://api.openai.com/v1/organization/external_keys
Registrácia konfigurácie EKM vráti external_key_id v tvare extkey_xxxx
Konfigurácie EKM sa aktivujú na úrovni projektu odoslaním external_key_id v tele existujúceho endpoint Create Project https://api.openai.com/v1/organization/projects
Obmedzenia
EKM musíte najprv otestovať na novom projekte prostredníctvom Management API.
Pre pracovné záťaže EKM odporúčame vytvoriť nové projekty. Ak však chcete EKM v existujúcom projekte, môžeme vás pridať do feature flagu. Pred zavedením EKM do existujúcich produkčných projektov si všimnite tieto osvedčené postupy.
Najprv vo svojom testovacom projekte EKM API otestujte všetky funkcie API, ktoré používate v produkcii
Použite postupné zavádzanie namiesto nasadenia EKM do všetkých produkčných projektov API naraz
Endpoints na úrovni organizácie
Registrácia externého kľúča vo vašej organizácii
AWS
Ukážková požiadavka
type: string – vždy „aws“
name: string – ľahko rozpoznateľný názov vašej konfigurácie
role_arn: string – Role ARN, ktorý OpenAI prevezme vo vašom cloude
kms_arn: string – ARN systému Key Management System pre hlavný kľúč, ktorý spravujete
external_id: string – ID vašej organizácie alebo ID projektu 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>
}'Ukážková odpoveď
{
"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
Ukážková požiadavka
type: string – vždy „gcp“,
name: string – ľahko rozpoznateľný názov vašej konfigurácie
workload_identity_project_number: string – 12-miestne číslo projektu GCP, v ktorom ste zaregistrovali Workload Identity OpenAI
workload_identity_pool_id: string – fond obsahujúci poskytovateľa Workload Identity, ktorého ste zaregistrovali pre OpenAI
workload_identity_provider_id: string – poskytovateľ Workload Identity, ktorého ste zaregistrovali pre OpenAI
audience: string – audience, ktorú má OpenAI odoslať v tokene, keď prevezmeme rolu cez váš GCP STS
kms_project_id: string – názov projektu GCP, v ktorom sa nachádza váš KMS
kms_key_ring_name: string – key ring systému Key Management System obsahujúci hlavný kľúč, ktorý spravujete
kms_key_name: string – názov hlavného kľúča systému Key Management System
kms_key_location: string – región, v ktorom sa nachádza váš hlavný kľúč systému Key Management System
Ak je váš KMS v inom projekte GCP než ten, v ktorom ste zaregistrovali Workload Identity OpenAI, uistite sa, že projekt obsahujúci Workload Identity OpenAI má aspoň povolený KMS. Prejdite na 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"
}'Ukážková odpoveď
{
"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
Ukážková požiadavka
type: string – vždy „azure“,
name: string – ľahko rozpoznateľný názov vašej konfigurácie
tenant_id: string – UUID vášho tenanta Azure
vault_uri: string – URI trezora Azure obsahujúceho hlavný kľúč, ktorý spravujete
key_name: string – názov hlavného kľúča Azure Key Vault, ktorý spravujete.
Musí mať tvar <org-xxx>--<any_name>
kde org-xxx je ID vašej organizácie OpenAI, ktoré nájdete na 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"
}'Ukážková odpoveď
{
"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"
}Odstránenie externého kľúča zaregistrovaného vo vašej organizácii
Poznámka: Externý kľúč môžete odstrániť iba vtedy, keď nie je priradený k žiadnym aktívnym projektom API ani pracovnému priestoru. Ak je priradený k aktívnemu projektu API, najprv tento projekt archivujte. Ak je priradený k pracovnému priestoru, kľúč nemožno odstrániť.
Ukážková požiadavka
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Ukážková odpoveď
{
"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>"
}Získanie externých kľúčov zaregistrovaných vo vašej organizácii
Ukážková požiadavka
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Ukážková odpoveď
{
"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"
}Overenie externého kľúča
Tento endpoint môžete použiť na kontrolu viacerých vecí
Vaša externá cloudová konfigurácia zostáva po vykonaní zmien platná pre OpenAI (zobrazí sa úspešná odpoveď)
Odvolanie kľúča prebehlo správne, OpenAI ho spracúva a prejaví sa po uplynutí 1-hodinovej TTL vyrovnávacej pamäte (zobrazí sa chybová odpoveď)
Ukážková požiadavka
curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Ukážková odpoveď
{
"status": "success"
}Alebo sa zobrazí chyba od poskytovateľa cloudu.
Endpoints na úrovni projektu
Vytvorenie nového projektu pomocou ID externého kľúča
Je to rovnaké ako existujúci endpoint Create Project, ibaže v požiadavke a odpovedi je navyše parameter external_key_id.
Ukážková požiadavka
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"
}'Ukážková odpoveď
{
"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,
}[Obmedzené] Aktualizácia existujúceho projektu pomocou ID externého kľúča
Je to rovnaké ako existujúci endpoint Update Project, ibaže v požiadavke a odpovedi je navyše parameter external_key_id.
Pre pracovné záťaže EKM odporúčame vytvoriť nové projekty API. Ak chcete EKM vo všetkých existujúcich projektoch API, požiadajte svojho account directora a pridáme vás do feature flagu. Pred zavedením EKM do existujúcich produkčných projektov si všimnite tieto osvedčené postupy.
Najprv vo svojom testovacom projekte EKM API otestujte všetky funkcie API, ktoré používate v produkcii
Použite postupné zavádzanie namiesto nasadenia EKM do všetkých produkčných projektov API naraz
Ukážková požiadavka
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"
}'Výpis všetkých projektov vo vašej organizácii
Je to rovnaké ako existujúci endpoint, ibaže odpoveď API navyše obsahuje external_key_id
Ukážková požiadavka
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Ukážková odpoveď
{
"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
}