如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

API 密钥和服务账户

为开发工作、应用和自动化任务选择身份和凭据。

API 密钥是用于验证请求身份的机密凭据。服务账户是供应用或自动化工作负载使用的非人类身份。服务账户可以拥有 API 密钥:在同一套身份验证机制中,服务账户提供身份,密钥提供凭据。

个人开发时,请使用您自己的项目密钥。如果应用或自动化任务需要独立的权限和生命周期,请使用服务账户。通过管理 API 管理组织时,请使用管理 API 密钥。

选择合适的身份

工作负载 身份和凭据 选择原因
个人在本地进行开发或探索 您的用户账户和项目 API 密钥 发起请求时使用的是您在项目中的访问权限。
已部署的应用、定时作业或 CI 工作流 项目服务账户及其 API 密钥 工作负载拥有独立于开发者个人的身份。
使用 OpenAI 支持的身份提供商的工作负载 配置了工作负载身份联合的项目服务账户 工作负载无需存储长期有效的 OpenAI API 密钥即可完成身份验证。
用于创建项目或管理项目服务账户及密钥的自动化任务 管理 API 密钥 管理组织需要使用专门的管理端点和权限。

使用用户密钥发起请求时,适用的是密钥所有者的访问权限。请勿让整个团队共用一名开发者的密钥,也不要将该开发者的个人身份用作生产应用的永久身份。

每个服务账户都属于一个项目。请在项目内为每个工作负载分配所需的身份和访问权限。为不同应用或环境分别创建项目,可以隔离各自的资源、成员和用量。如果只需区分同一项目中的工作负载,可以分别创建服务账户,无需另建项目。

了解权限和范围

API 密钥能执行哪些操作,取决于密钥本身及其所有者的权限。设置密钥的权限范围可以限制密钥能执行的操作,但无法授予用户或服务账户本身没有的权限。即使密钥未设置范围限制,也只能在其所有者的有效权限内使用。

仅向服务账户分配其工作负载所需的角色,然后根据需要限制其密钥的权限范围。有关授权模型,请参阅权限和角色。如需了解如何通过配置创建身份、分配自定义角色并签发限定权限范围的密钥,请参阅使用 Terraform 配置服务账户。

管理 API 密钥与项目工作负载密钥的用途不同。请将管理凭据保存在负责创建和管理资源的可信服务中。应用发起模型请求时,应使用项目服务账户的凭据。

自动管理项目和密钥

如果您的应用需要为客户创建项目,使用项目服务账户可以让每个工作负载拥有独立的身份,无需依赖运行配置流程的开发者。负责配置的服务使用管理 API 来管理项目及其服务账户,配置完成的应用则使用自己的项目凭据。

相关管理操作如下:

操作 用途
创建项目 创建工作负载的资源和服务账户所属的项目。
创建服务账户 在该项目中为工作负载创建身份。使用 create_service_account_only 选项时,只创建服务账户,不分配默认角色,也不生成初始 API 密钥。
创建服务账户 API 密钥 为现有服务账户签发密钥,并按需设置密钥的权限范围和到期时间。
管理项目 API 密钥 列出、检索、更新或撤销现有的项目密钥,包括服务账户密钥。

项目 API 密钥管理端点不支持代其他用户创建归其个人所有的项目密钥。如需通过程序创建密钥,请使用服务账户,并调用相应的密钥创建端点。

创建服务账户时,如果不分配默认角色,该账户不会自动获得发起模型请求的权限。请先分配所需权限,再使用该账户的凭据。创建密钥时也必须遵守组织和项目的密钥策略,服务账户无法绕过这些策略。

管理凭据的生命周期

API 仅在创建服务账户密钥时返回完整的密钥值。请将密钥保存在机密管理工具中,并在服务器端将其提供给工作负载。切勿在浏览器代码、移动应用、版本控制系统、日志或返回给客户的响应中包含密钥。

请根据组织和项目的策略设置到期时间。轮换密钥时,先签发新密钥,再更新工作负载以使用新密钥,确认工作负载运行正常后再撤销旧密钥。更换密钥时,服务账户可以继续使用原有身份。

工作负载的职责发生变化时,请重新审查其访问权限。停用工作负载时,请撤销其凭据。有关密钥治理和到期策略,请参阅生产环境 API 密钥指南。如需在不存储 API 密钥的情况下完成身份验证,请参阅工作负载身份联合。