摘要

存取權限

EKM endpoints 可透過 Admin API Key 在 Management API 中存取。https://platform.openai.com/settings/organization/admin-keys（請勿使用一般 API key）。Admin API keys 可供組織擁有者使用。
使用 api.external_keys.write 建立或刪除外部金鑰，並使用 api.external_keys.read 列出或驗證外部金鑰。只有在單一金鑰需要同時執行讀取和寫入操作時，才需要兩個 scope。
目前我們需要為你的組織啟用功能旗標，才可使用這些 endpoints。如果你在現有的 List Projects endpoint 回傳中看到 external_key_id ，即表示你已取得功能旗標：https://api.openai.com/v1/organization/projects

用法

你的 EKM 設定會透過新的 endpoint https://api.openai.com/v1/organization/external_keys 在組織層級註冊
註冊 EKM 設定後，會回傳格式為 extkey_xxxx 的 external_key_id
EKM 設定會在專案層級啟用，做法是在現有 Create Project https://api.openai.com/v1/organization/projects endpoint 的本文中傳入 external_key_id

限制

你必須先透過 Management API 在新專案上測試 EKM。
我們建議為你的 EKM 工作負載啟動新的專案。不過，如果你想在現有專案上使用 EKM，我們可以將你加入功能旗標。將 EKM 推出至現有生產專案前，請留意以下最佳做法。
- 先在測試 EKM API 專案中，測試你在生產環境使用的所有 API 功能
- 採用分階段推出，而非一次過在所有生產 API 專案上啟用 EKM

組織層級 endpoints

在你的組織註冊外部金鑰

AWS

請求範例

type：string - 一律為「aws」
name：string - 你的設定易記名稱
role_arn：string - OpenAI 將在你的雲端中代入的角色 ARN
kms_arn：string - 你管理的主金鑰所屬 Key Management System ARN
external_id：string - 你的組織 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：string - 一律為「gcp」,
name：string - 你的設定易記名稱
workload_identity_project_number：string - 你註冊 OpenAI workload identity 的 12 位數 GCP 專案編號
workload_identity_pool_id：string - 包含你為 OpenAI 註冊的 Workload Identity provider 的 pool
workload_identity_provider_id：string - 你為 OpenAI 註冊的 Workload Identity provider
audience: string - 當我們透過你的 GCP STS 代入角色時，OpenAI 應在 Token 中傳入的 audience
kms_project_id: string - 你的 KMS 所在 GCP 專案名稱
kms_key_ring_name：string - 包含你管理的主金鑰的 Key Management System key ring
kms_key_name：string - Key Management System 主金鑰名稱
kms_key_location：string - 你的 Key Management System 主金鑰所在區域

如果你的 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：string - 一律為「azure」,
name：string - 你的設定易記名稱
tenant_id：string - 你的 Azure tenant UUID
vault_uri：string - 包含你管理的主金鑰的 Azure vault URI
key_name：string - 你管理的 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"
}

驗證外部金鑰

你可以使用此 endpoint 檢查多項事項

你變更外部雲端設定後，該設定對 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 建立新專案

這與現有 Create Project endpoint 相同，但請求和回應中新增了 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 更新現有專案

這與現有 Update Project endpoint 相同，但請求和回應中新增了 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"
}'

列出你組織中的所有專案

這與現有 endpoint 相同，但 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
}

Management API 中的 EKM（外部金鑰）

摘要

存取權限

用法

限制

組織層級 endpoints

在你的組織註冊外部金鑰

AWS

請求範例

回應範例

GCP

請求範例

回應範例

Azure

請求範例

回應範例

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

請求範例

回應範例

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

請求範例

回應範例

驗證外部金鑰

請求範例

回應範例

專案層級 endpoints

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

請求範例

回應範例

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

請求範例

列出你組織中的所有專案

請求範例

回應範例

這篇文章對你有幫助嗎？