概要

访问权限

可凭借 Admin API 密钥，在 Management API 中访问 EKM 端点。https://platform.openai.com/settings/organization/admin-keys（请勿使用普通 API 密钥）。组织所有者可使用管理员 API 密钥。
请使用 api.external_keys.write 创建或删除外部密钥，使用 api.external_keys.read 罗列或验证外部密钥。只有在单个密钥需要同时执行读取与写入操作时，才需要同时配置以上两个作用域。
目前我们需要为您的组织开通对应功能标记，以开放此类端点的访问权限。若现有列出项目端点会返回 **external_key_id**，即代表您已开通对应功能标记，详情可参考：https://api.openai.com/v1/organization/projects

使用说明

你可通过新端点 https://api.openai.com/v1/organization/external_keys，在组织层级完成 EKM 配置注册
完成 EKM 配置注册后，系统会返回格式为 extkey_xxxx 的 external_key_id
在现有创建项目端点 https://api.openai.com/v1/organization/projects 的请求体中传入 external_key_id，即可在项目层级启用 EKM 配置。

限制条件

你必须先通过 Management API 在新项目中完成 EKM 测试。
我们建议你新建项目，以承载 EKM 相关业务负载。如果你需要在现有项目中启用 EKM，我们可为您开通对应功能标记。在将 EKM 部署至线上生产项目前，请遵守以下最佳实践。
- 请优先在 EKM 测试项目中，完整验证线上环境用到的全部 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 工作负载身份的 12 位 GCP 项目编号
workload_identity_pool_id：字符串，存放你为 OpenAI 注册的工作负载身份提供商的资源池
workload_identity_provider_id：字符串，你专门为 OpenAI 注册的工作负载身份提供商
audience：字符串，OpenAI 通过你的 GCP STS 承接角色时，需要在 token 中携带的访问受众标识
kms_project_id：字符串，你 KMS 服务所属的 GCP 项目名称
kms_key_ring_name：字符串，存放你管理的主密钥的密钥管理系统密钥环
kms_key_name：字符串，密钥管理系统主密钥的名称
kms_key_location：字符串，你密钥管理系统主密钥部署的地域

如果你的 KMS 所属 GCP 项目，与注册 OpenAI 工作负载身份的项目不一致，请前往 https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview，确保前者已开启 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 租户唯一标识
vault_uri：字符串，存放你管理主密钥的 Azure 保管库访问地址
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 参数。

我们建议你新建 API 项目，以承载所有 EKM 相关业务。如果你希望在现有的所有 API 项目中启用 EKM，请联系你的客户经理，我们会为你开启该功能标记。在将 EKM 部署至线上生产项目前，请遵守以下最佳实践。

请优先在 EKM 测试项目中，完整验证线上环境用到的全部 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

请求示例

列出你的组织中的所有项目

请求示例

响应示例

这篇文章对你有帮助吗？