摘要

存取權限

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：string - 你的設定易於辨識的名稱
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 工作負載身分識別時所使用的數字 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"
}

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

請注意：只有在外部金鑰未與任何使用中的 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 設定",
  "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 設定",
      "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": "organization.project",
  "id": "proj_xxxxx",
  "name": "Some Project",
  "external_key_id": "extkey_xxxx",
  "created_at": 1740012721,
  "archived_at": null,
  "status": "active"
}

[受限] 使用外部金鑰 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 更新現有專案

範例要求

列出貴組織中的所有專案

範例要求

範例回應

這篇文章有幫助嗎？