摘要

存取

可透過管理 API中的管理員 API 金鑰存取 EKM 端點。https://platform.openai.com/settings/organization/admin-keys（請勿使用一般 API 金鑰）。管理員 API 金鑰僅供組織擁有者使用。
使用 api.external_keys.write 建立或刪除外部金鑰，使用 api.external_keys.read 列出或驗證外部金鑰。只有在單一金鑰必須同時執行讀取及寫入操作時，才需要同時具備這兩個 scope。
目前我們需要為你的組織啟用功能旗標，才能使用這些端點。若你在現有的「列出專案」端點中看到回傳 **external_key_id **，即表示你已獲啟用此功能旗標：https://api.openai.com/v1/organization/projects

用法

你的 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

組織層級端點

在你的組織上註冊外部金鑰

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 的 workload identity 註冊所在的 12 位數 GCP 專案編號
workload_identity_pool_id：字串 - 包含你為 OpenAI 註冊的 Workload Identity 提供者的集區
workload_identity_provider_id：字串 - 你為 OpenAI 註冊的 Workload Identity 提供者
audience:：字串 - 當我們透過你的 GCP STS 假設角色時，OpenAI 應在 token 中傳入的 audience
kms_project_id:：字串 - 你的 KMS 所在 GCP 專案的名稱
kms_key_ring_name：字串 - 包含你所管理主金鑰的金鑰管理系統 key ring
kms_key_name：字串 - 金鑰管理系統主金鑰的名稱
kms_key_location：字串 - 金鑰管理系統主金鑰所在的區域

如果你的 KMS 與你為 OpenAI 的 Workload Identity 註冊所在專案分屬不同的 GCP 專案，請前往 https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview，確保包含 OpenAI Workload Identity 的專案至少已啟用 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 tenant UUID
vault_uri：字串 - 包含你所管理主金鑰的 Azure vault 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"
}

刪除已在你的組織上註冊的外部金鑰

注意：只有在外部金鑰未與任何啟用中的專案關聯時，才可將其刪除。若它與啟用中的專案相關聯，你必須先封存該專案。

範例請求

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

或者，顯示來自雲端供應商的錯誤。

專案層級端點

使用外部金鑰 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": "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,
}

[受限制] 使用外部金鑰 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
}

管理 API 中的 EKM（外部金鑰）

摘要

存取

用法

限制

組織層級端點

在你的組織上註冊外部金鑰

AWS

範例請求

範例回應

GCP

範例請求

範例回應

Azure

範例請求

範例回應

刪除已在你的組織上註冊的外部金鑰

範例請求

範例回應

取得已在你的組織上註冊的外部金鑰

範例請求

範例回應

驗證外部金鑰

範例請求

範例回應

專案層級端點

使用外部金鑰 ID 建立新專案

範例請求

範例回應

[受限制] 使用外部金鑰 ID 更新現有專案

範例請求

列出你組織上的所有專案

範例請求

範例回應

這篇文章對你有幫助嗎？