摘要
存取
你可以使用管理員 API 密鑰，透過管理 API 存取 EKM 端點。https://platform.openai.com/settings/organization/admin-keys（請勿使用一般 API 密鑰）。組織擁有者可使用管理員 API 密鑰。
使用
api.external_keys.write建立或刪除外部密鑰，並使用api.external_keys.read列出或驗證外部密鑰。只有需要同時執行讀取和寫入操作的密鑰，才需要具備這兩個權限範圍。目前，我們需要為你的組織啟用功能旗標，才能讓你存取這些端點。如果現有的「列出項目」端點 https://api.openai.com/v1/organization/projects 傳回了 external_key_id，即表示功能旗標已啟用。
使用方式
你的 EKM 設定會透過新端點 https://api.openai.com/v1/organization/external_keys 在組織層級註冊。
註冊 EKM 設定後，系統會傳回格式為 extkey_xxxx 的 external_key_id。
在現有的「建立項目」端點 https://api.openai.com/v1/organization/projects 的請求主體中傳入 external_key_id，即可在項目層級啟用 EKM 設定。
限制
你必須先透過管理 API，在新項目中測試 EKM。
我們建議為 EKM 工作負載建立新項目。不過，如果你想在現有項目中使用 EKM，我們可以為你啟用功能旗標。在現有正式環境項目中部署 EKM 之前，請留意以下最佳實踐。
先在 EKM 測試用 API 項目中，測試你在正式環境中使用的所有 API 功能。
採用逐步部署的方式，而非一次過在所有正式環境 API 項目中啟用 EKM。
組織層級 endpoints
在你的組織註冊外部金鑰
AWS
請求範例：
type：字串 — 一律為「aws」
name：字串 — 便於識別這項設定的名稱
role_arn：字串 — OpenAI 將在你的雲端環境中擔任的角色 ARN
kms_arn：字串 — 你所管理的主密鑰在密鑰管理系統中的 ARN
external_id：字串 — 你的組織 ID 或 API 項目 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>"
}'回應範例：
{
"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
請求範例：
type：字串 — 一律為「gcp」，
name：字串 — 便於識別這項設定的名稱
workload_identity_project_number：字串 — 你註冊 OpenAI 工作負載身分所在的 GCP 項目的數字編號
workload_identity_pool_id：字串 — 包含你為 OpenAI 註冊的工作負載身分供應商的集區
workload_identity_provider_id：字串 — 你為 OpenAI 註冊的工作負載身分供應商
audience：字串 — OpenAI 透過你的 GCP STS 擔任角色時，應在權杖中傳入的目標對象
kms_project_id：字串 — 你的 KMS 所在的 GCP 項目名稱
kms_key_ring_name：字串 — 密鑰管理系統中包含你所管理的主密鑰的密鑰環
kms_key_name：字串 — 密鑰管理系統中的主密鑰名稱
kms_key_location：字串 — 密鑰管理系統中的主密鑰所在的區域
如果你的 KMS 與你註冊 OpenAI 工作負載身分所在的 GCP 項目不同，請前往 https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview，確保包含 OpenAI 工作負載身分的項目至少已啟用 KMS。
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"
}'回應範例：
{
"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
請求範例：
type：字串 — 一律為「azure」，
name：字串 — 便於識別這項設定的名稱
tenant_id：字串 — 你的 Azure 租戶 UUID
vault_uri：字串 — 包含你所管理的主密鑰的 Azure 保存庫 URI
key_name：字串 — 你所管理的 Azure Key Vault 主密鑰的名稱。
名稱必須採用 <org-xxx>--<any_name> 的格式
其中 org-xxx 是你的 OpenAI 組織 ID，可在 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"
}'回應範例：
{
"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"
}刪除已在組織中註冊的外部密鑰
注意：只有未與任何使用中的 API 項目或工作區關聯的外部密鑰，才可以刪除。如果密鑰與使用中的 API 項目關聯，請先封存該項目。如果密鑰與工作區關聯，則無法刪除。
請求範例
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"回應範例
{
"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>"
}取得已在組織中註冊的外部密鑰
請求範例
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"回應範例
{
"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"
}驗證外部密鑰
你可以使用此端點檢查以下事項：
變更外部雲端設定後，該設定是否仍可供 OpenAI 使用（你會看到成功回應）。
密鑰撤銷操作是否正確完成、OpenAI 是否正在處理，以及是否將在 1 小時的快取存留時間（TTL）屆滿後生效（你會看到錯誤回應）。
請求範例
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"回應範例
{
"status": "success"
}或者，由雲端供應商傳回錯誤。
專案層級 endpoints
使用外部密鑰 ID 建立新項目
這與現有的「建立項目」端點相同，只是在請求和回應中新增了 external_key_id 參數。
請求範例
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"
}'回應範例
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}[受限功能] 使用外部密鑰 ID 更新現有項目
這與現有的「更新項目」端點相同，只是在請求和回應中新增了 external_key_id 參數。
我們建議為 EKM 工作負載建立新的 API 項目。如果你想在所有現有 API 項目中使用 EKM，請向你的客戶總監提出申請，我們會為你啟用功能旗標。在現有正式環境項目中部署 EKM 之前，請留意以下最佳實踐。
先在 EKM 測試用 API 項目中，測試你在正式環境中使用的所有 API 功能。
採用逐步部署的方式，而非一次過在所有正式環境 API 項目中啟用 EKM。
請求範例
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"
}'列出組織中的所有項目
這與現有端點相同，只是在 API 回應中新增了 external_key_id。
請求範例
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"回應範例
{
"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
}