摘要

存取權限

EKM 端點可透過管理員 API 金鑰在管理 API 中存取。https://platform.openai.com/settings/organization/admin-keys(請勿使用一般 API 金鑰)。管理員 API 功能可供組織擁有者使用。
使用 Api.External_key.Write 來建立或刪除外部金鑰，並使用 api.external_keys.read 來列出或驗證外部金鑰。只有在單一金鑰必須同時執行讀取和寫入作業時，才需要這兩種範圍。
目前我們需要為貴組織啟用功能旗標，以便使用這些端點。如果你看到現有的「列出專案」端點傳回 **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
EKM 設定可在專案等級啟用，方法是在現有的「建立專案」https://api.openai.com/v1/organization/projects 要求主體中傳入 external_key_id端點

限制

你必須先透過管理 API 在新專案中測試 EKM。
我們建議為你的 EKM 工作負載啟動新的專案。不過，如果你想在現有的專案中使用 EKM，我們可以將你加入功能旗標。在將 EKM 推出至現有的正式環境專案之前，請注意以下最佳做法。
- 請先在測試用的 EKM API 專案中測試所有會在正式環境使用的 API 功能
- 改為逐步推出，而不是一次將 EKM 套用至正式環境中的所有 API 專案

組織等級端點

在貴組織中註冊外部金鑰

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：string - 你的設定易於辨識的名稱
workload_identity_project_number：string - 你註冊 OpenAI 工作負載身分識別的 12 位數 GCP 專案編號
workload_identity_pool_id：字串 - 包含你為 OpenAI 註冊之工作負載身分提供者的集區
workload_identity_provider_id：字串 - 你為 OpenAI 註冊的工作負載身分提供者
audience：字串 - 當我們透過你的 GCP STS 擔任角色，OpenAI 應在 Token 中傳遞的 audience 參數
kms_project_id：字串 - 你的 KMS 所在的 GCP 專案名稱
kms_key_ring_name：字串 - 包含你管理的主金鑰的金鑰管理系統金鑰圈
kms_key_name：字串 - 金鑰管理系統主金鑰的名稱
kms_key_location：字串 - 你的金鑰管理系統主金鑰所在的區域

如果你的 KMS 位於與你註冊 OpenAI 的 Workload Identity 不同的 GCP 專案中，請確認包含 OpenAI 的工作負載身分的專案至少已啟用 KMS，你可以前往 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"
}'

範例回應

{
  "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：string - 你的設定易於辨識的名稱
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"
}

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

請注意：只有在外部金鑰未與任何使用中的專案相關聯時，才能將其刪除。如果它與使用中的專案相關聯，必須先將其封存。

範例要求

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 設定",
  "role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}

取得已註冊於貴組織的外部 API 金鑰

範例要求

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 建立新專案

這與現有的 Create Project 端點相同，差別在於要求與回應中新增了 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 端點相同，但在要求與回應中新增了 external_key_id 參數。

我們建議為你的 EKM 工作負載建立新的 API 專案。如果你想在現有的所有 API 專案中啟用 EKM，請聯絡你的客戶經理，我們會將你加入該功能旗標。在將 EKM 推出至現有的正式環境專案之前，請注意以下最佳做法。

請先在測試用的 EKM API 專案中測試所有會在正式環境使用的 API 功能
改為逐步推出，而不是一次將 EKM 套用至正式環境中的所有 API 專案

範例要求

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

範例要求

範例回應

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

範例要求

範例回應

取得已註冊於貴組織的外部 API 金鑰

範例要求

範例回應

驗證外部金鑰

範例要求

範例回應

專案等級的端點

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

範例要求

範例回應

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

範例要求

列出貴組織中的所有專案

範例要求

範例回應

這篇文章有幫助嗎？