Skip to main content
密钥库(vault)和凭据(credential)是身份验证原语,让您可以为第三方服务注册一次凭据,然后在创建会话时通过 ID 引用它们。这意味着您无需运行自己的密钥存储、无需在每次调用时传输令牌,也不会丢失智能体代表哪个最终用户执行操作的记录。 密钥库引用是每个会话的参数,因此您可以在 agent 资源粒度上管理您的产品,在 session 资源粒度上管理您的用户。
托管智能体 API 请求需要 managed-agents-2026-04-01 Beta 请求头,但记忆存储端点除外,它们使用 agent-memory-2026-07-22。SDK 会自动设置正确的 Beta 请求头。请参阅Beta 请求头

创建密钥库

密钥库和凭据的作用域为工作区,这意味着拥有同一工作区 API 密钥的任何人都可以在创建会话时引用它们。要撤销访问权限,请删除密钥库或凭据。
密钥库是与最终用户关联的 credentials 集合。为其指定一个 display_name,并可选择使用 metadata 对其进行标记,以便您可以将其映射回您自己的用户记录。
响应是完整的密钥库记录:

添加凭据

支持两种凭据类别:
  • MCP 凭据mcp_oauthstatic_bearer):每个凭据以 mcp_server_url 为键。当智能体在会话运行时连接到该 URL 的服务器时,令牌会自动注入。
  • 环境变量environment_variable):每个凭据以 secret_name(环境变量名称)为键,并以不透明占位符的形式存储在沙箱中。当智能体发起出站请求时,不透明占位符会在出口处被替换为真实密钥。智能体永远不会看到密钥值。对于任何通过环境变量进行身份验证的服务(例如 CLI、SDK 或直接 API 调用),请使用此类别。
您提供的实际凭据值(tokenaccess_tokenrefresh_tokenclient_secretsecret_value)被视为敏感的只写字段,永远不会在 API 响应中返回。
环境变量凭据(environment_variable)尚不支持与自托管沙箱一起使用。
当 MCP 服务器使用 OAuth 2.0 时,请使用 mcp_oauth。如果您提供 refresh 块,OMA 会在访问令牌过期时代表您刷新它。refresh.token_endpoint_auth.type 字段指示如何对刷新调用进行身份验证:
  • none:公共客户端
  • client_secret_basic:使用客户端密钥的 HTTP Basic 身份验证
  • client_secret_post:客户端密钥放在 POST 正文中
凭据按提供的原样存储,直到会话运行时才会被验证。无效凭据会在会话期间表现为身份验证错误或下游错误,该错误会被发出,但不会阻止会话继续进行。 约束:
  • 每个密钥库中键必须唯一。 mcp_server_url(MCP 凭据)和 secret_name(环境变量凭据)在密钥库的活动凭据中必须唯一。创建重复项会返回 409。
  • 键不可变。 要更改 mcp_server_urlsecret_name,请归档该凭据并创建一个新凭据。
  • 每个密钥库最多 20 个凭据。

在创建会话时引用密钥库

创建会话时传递 vault_ids
运行时行为:
  • 当没有 MCP 凭据通过 mcp_server_url 匹配时,连接会以未经身份验证的方式尝试,如果服务器要求身份验证则会出错。
  • 当多个密钥库包含匹配的凭据时,第一个匹配的密钥库胜出。
  • 多智能体会话中,密钥库凭据适用于每个线程。如果某个智能体自身的定义声明了匹配的 MCP 服务器,则该智能体使用这些凭据进行身份验证。请参阅将智能体连接到 MCP 服务器

轮换凭据

密钥值、display_name 以及(在环境变量凭据上的)injection_location 可以更新。injection_location 的更新按字段合并,如添加凭据的”环境变量”选项卡中所述。对于正在运行的会话,injection_location 更新的传播方式与密钥轮换相同:会话的凭据会在不重启的情况下重新解析(如凭据生命周期中所述),更新后的位置适用于该会话后续的出站请求。结构性字段(mcp_server_urlsecret_nametoken_endpointclient_id)在创建后被锁定。要更改它们,请归档该凭据并创建一个新凭据。

凭据生命周期

凭据会在会话期间和密钥库生命周期内定期重新解析。这确保凭据的轮换、归档或删除能够在不重启的情况下传播到正在运行的会话。 要在凭据被归档、删除或刷新失败时收到通知,您可以订阅与这些生命周期变更相关联的密钥库和凭据 webhooks
这不是 webhooks 的完整列表;请参阅订阅 webhooks 获取完整列表。
对于 mcp_oauth 凭据,重新解析还会在访问令牌过期时刷新它。如果刷新失败,会发出 vault_credential.refresh_failed 事件。

诊断 OAuth 刷新失败

要诊断刷新失败的原因,请调用 POST /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate(或在 SDK 中调用 client.beta.vaults.credentials.mcp_oauth_validate(...))。这让您可以决定如何处理失败;正确的操作取决于错误类型。 顶层的 status 告诉您下一步该做什么:
  • valid:令牌有效;无需操作。
  • invalid:授权已失效,或 OAuth 服务器以 4xx 拒绝了刷新。提示最终用户重新授权。
  • unknown:瞬时错误(5xx、429 或网络故障)。等待后重试。
响应是一个 vault_credential_validation 对象。mcp_probe 包含失败的 MCP 握手步骤;refresh 包含尝试刷新的结果。

其他操作

  • 列出密钥库或凭据: 分页,最新的在前。默认排除已归档的记录(传递 include_archived=true 以包含它们)。
  • 归档密钥库: POST /v1/vaults/{id}/archive。级联到所有凭据。密钥会被清除;记录会被保留以供审计。引用此密钥库的未来会话会失败;正在运行的会话会继续。
  • 归档凭据: POST /v1/vaults/{id}/credentials/{cred_id}/archive。清除密钥负载;凭据键(mcp_server_urlsecret_name)仍然可见,并被释放以供替换凭据使用。
  • 删除密钥库或凭据: 硬删除。记录不会被保留。如果您需要审计跟踪,请使用归档。