Buod
Access
Maa-access ang mga EKM endpoint sa Management API gamit ang isang Admin API Key. https://platform.openai.com/settings/organization/admin-keys (huwag gumamit ng karaniwang API key). Available ang mga Admin API key sa mga may-ari ng organisasyon.
Gamitin ang
api.external_keys.writepara gumawa o mag-delete ng mga external key, at angapi.external_keys.readpara maglista, kumuha, o mag-validate ng mga external key. Kailangan lang ng isang key ang parehong scope kung gagamitin ito para sa parehong read at write na operasyon.
Paggamit
Inirerehistro ang iyong EKM configuration sa antas ng organisasyon sa pamamagitan ng bagong endpoint na https://api.openai.com/v1/organization/external_keys.
Kapag inirehistro mo ang iyong EKM configuration, magbabalik ito ng external_key_id na may format na extkey_xxxx.
Ina-activate ang mga EKM configuration sa antas ng project sa pamamagitan ng pagpasa ng external_key_id sa body ng request sa kasalukuyang Create Project endpoint na https://api.openai.com/v1/organization/projects.
Mga paghihigpit
Dapat mo munang subukan ang EKM sa isang bagong proyekto gamit ang Management API.
Inirerekomenda naming gumawa ng mga bagong proyekto para sa iyong mga EKM workload. Isaalang-alang ang mga sumusunod na inirerekomendang gawain bago mo ipatupad ang EKM sa iyong mga kasalukuyang production project.
Subukan muna sa iyong test EKM API project ang lahat ng API feature na ginagamit mo sa production.
Unti-unting ipatupad ang EKM sa halip na sabay-sabay itong ilapat sa lahat ng production API project.
Mga endpoint sa antas ng organisasyon
Magrehistro ng external key sa iyong organisasyon
AWS
Halimbawa ng request:
type: string - laging “aws”
name: string - Isang madaling makilalang pangalan para sa iyong configuration
role_arn: string - Ang ARN ng role na gagampanan ng OpenAI sa iyong cloud
kms_arn: string - Ang Key Management System ARN para sa master key na pinapamahalaan mo
external_id: string - Ang iyong Organization ID o API project 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>"
}'Halimbawang response:
{
"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
Halimbawa ng request:
type: string - laging “gcp”,
name: string - Isang madaling makilalang pangalan para sa iyong configuration
workload_identity_project_number: string - Ang numerong nakatalaga sa GCP project kung saan mo inirehistro ang workload identity ng OpenAI
workload_identity_pool_id: string - Ang pool na naglalaman ng Workload Identity provider na inirehistro mo para sa OpenAI
workload_identity_provider_id: string - Ang Workload Identity provider na inirehistro mo para sa OpenAI
audience: string - Ang audience na dapat ipasa ng OpenAI sa token kapag gumaganap kami ng role sa pamamagitan ng iyong GCP STS
kms_project_id: string - Ang pangalan ng GCP project kung saan naroon ang iyong KMS
kms_key_ring_name: string - Ang key ring ng Key Management System na naglalaman ng master key na pinapamahalaan mo
kms_key_name: string - Ang pangalan ng master key ng Key Management System
kms_key_location: string - Ang rehiyon kung saan naroon ang iyong master key ng Key Management System
Kung ang iyong KMS ay nasa ibang GCP project kaysa sa project kung saan mo inirehistro ang Workload Identity ng OpenAI, tiyaking naka-enable man lang ang KMS sa project na naglalaman ng Workload Identity ng OpenAI. Pumunta sa 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"
}'Halimbawang response:
{
"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
Halimbawa ng request:
type: string - laging “azure”,
name: string - Isang madaling makilalang pangalan para sa iyong configuration
tenant_id: string - Ang UUID ng iyong Azure tenant
vault_uri: string - Ang URI ng Azure vault na naglalaman ng master key na pinapamahalaan mo
key_name: string - Ang pangalan ng master key ng Azure Key Vault na pinapamahalaan mo.
Dapat itong may format na <org-xxx>--<any_name>
kung saan ang org-xxx ay ang iyong OpenAI Organization ID na makikita mo sa 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"
}'Halimbawang response:
{
"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"
}OCI
Mag-set up ng naka-enable na AES-256 key at bigyan ng access ang OpenAI. Dapat may free-form na openai_organization_id tag ang key na nakatakda sa iyong OpenAI Organization ID. Para sa mga hakbang sa pag-set up, tingnan ang: Pag-configure ng OCI Vault para sa Enterprise Key Management.
Halimbawang request:
type: string - palaging "oci"
purpose: string - "ekm"; ang default kapag hindi tinukoy
name: string - Isang madaling makilalang pangalan para sa iyong configuration
region: string - Ang rehiyon ng OCI kung saan naroon ang iyong vault at key
vault_ocid: string - Ang buong OCID ng iyong vault
key_ocid: string - Ang buong OCID ng iyong AES-256 key
Huwag ipasa ang key_version_ocid para sa EKM.
curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}'Halimbawang response:
{
"id": "extkey_xxxx",
"object": "organization.external_key",
"created_at": 1746175499,
"api_project_ids": [],
"type": "oci",
"purpose": "ekm",
"name": "OCI EKM Config",
"region": "us-ashburn-1",
"vault_ocid": "<VAULT_OCID>",
"key_ocid": "<AES_KEY_OCID>"
}Nagbabalik ang API ng HTTP 200 kapag matagumpay ang operasyon. I-save ang ibinalik na id at gamitin ito bilang external_key_id kapag gumagawa ng proyekto. Nalalapat din sa mga pagpaparehistro sa OCI ang mga kasalukuyang operasyon para sa paglilista, pagkuha, pag-validate, at pag-delete.
Para sa PSP recovery, gumamit ng hiwalay na pagpaparehistro ng RSA-3072 na may purpose: "psp_decryption" at eksaktong key_version_ocid. Itakda ang psp_decryption_key_id sa ID ng pagpaparehistro nito sa OpenAI. Read access lang sa metadata at mga public key para sa RSA key na iyon ang kailangan ng OpenAI. Para sa kumpletong pag-set up, tingnan ang: Mag-set up ng mga asymmetric key — OCI Vault.
Mag-delete ng external key na nakarehistro sa iyong organisasyon
Tandaan: Hindi puwedeng mag-delete habang ginagamit ng isang aktibong proyekto o workspace ang pagpaparehistro. Para sa EKM, i-archive muna ang mga kaugnay na API project; mananatiling protektado ang pagpaparehistro ng EKM na nauugnay sa workspace. Para sa PSP recovery, palitan o alisin ang halaga ng psp_decryption_key_id sa bawat aktibong proyektong tumutukoy sa pagpaparehistro bago ito i-delete. Hindi nade-delete ang cloud key kapag nag-delete ng pagpaparehistro sa OpenAI.
Halimbawang request
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Halimbawa ng response
{
"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>"
}Kunin ang mga external key na nakarehistro sa iyong organisasyon
Kung walang filter na purpose, kasama sa listahan ang mga pagpaparehistro para sa EKM at PSP recovery. Gamitin ang ?purpose=ekm o ?purpose=psp_decryption para mag-filter ayon sa layunin.
Halimbawang request
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Halimbawa ng response
{
"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"
}Mag-validate ng external key
Gamitin ang validation para tiyaking maa-access pa rin ng OpenAI ang iyong cloud key.
Para sa EKM, sinusuri ng OpenAI kung kaya nitong mag-encrypt at mag-decrypt gamit ang key. Para sa kung paano gumagana ang pagbawi ng access at pag-cache, tingnan ang: gabay sa lifecycle ng key.
Para sa PSP recovery, kinukuha ng OpenAI ang public key ng nakarehistrong bersyon at inihahambing ito sa nakaimbak na snapshot. Hindi kinukumpirma ng matagumpay na validation na kayang mag-decrypt ng iyong recovery identity. Hindi inaalis o pinapalitan ng nabigong validation ang nakaimbak na snapshot ng public key.
Kapag kumukuha ng pagpaparehistro gamit ang GET, ibinabalik nito ang nakaimbak na configuration at hindi nito muling sinusuri ang access sa iyong cloud key.
Halimbawang request
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Halimbawang response
{
"status": "success"
}O kaya, may lumitaw na error mula sa cloud provider.
Mga endpoint sa antas ng proyekto
Gumawa ng bagong project na may external key ID
Katulad ito ng kasalukuyang Create Project endpoint, pero may dagdag na external_key_id parameter sa request at response.
Halimbawa ng request
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"
}'Halimbawa ng response
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}Mag-update ng kasalukuyang proyekto gamit ang external key ID
Katulad ito ng kasalukuyang Update Project endpoint, pero may dagdag na external_key_id parameter sa request at response.
Inirerekomenda naming gumawa ng mga bagong API project para sa iyong mga EKM workload. Isaalang-alang ang mga sumusunod na inirerekomendang gawain bago mo ipatupad ang EKM sa iyong mga kasalukuyang production project.
Subukan muna sa iyong test EKM API project ang lahat ng API feature na ginagamit mo sa production.
Unti-unting ipatupad ang EKM sa halip na sabay-sabay itong ilapat sa lahat ng production API project.
Halimbawang request
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"
}'Ilista ang lahat ng project sa inyong organisasyon
Katulad ito ng kasalukuyang endpoint, pero may dagdag na external_key_id sa API response.
Halimbawa ng request
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Halimbawa ng response
{
"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
}