使用保管库进行身份验证

"Vaults"（保管库）和 "credentials"（凭据）是身份验证原语，允许您为第三方服务注册一次凭据，然后在创建会话时通过 ID 引用它们。这意味着您无需运行自己的密钥存储、在每次调用时传输令牌，也不会失去对智能体代表哪个最终用户执行操作的追踪。

保管库引用是一个会话级参数，因此您可以在 agent 资源粒度上管理您的产品，在 session 资源粒度上管理您的用户。



创建保管库

保管库是与某个最终用户关联的 credentials 集合。为其指定一个 display_name，并可选择使用 metadata 对其进行标记，以便将其映射回您自己的用户记录。

VAULT_ID=$(ant beta:vaults create \
  --display-name "Alice" \
  --metadata '{external_user_id: usr_abc123}' \
  --transform id --raw-output)
echo "$VAULT_ID"  # "vlt_01ABC..."

响应是完整的保管库记录：

{
  "type": "vault",
  "id": "vlt_01ABC...",
  "display_name": "Alice",
  "metadata": { "external_user_id": "usr_abc123" },
  "created_at": "2026-03-18T10:00:00Z",
  "updated_at": "2026-03-18T10:00:00Z",
  "archived_at": null
}



添加凭据

支持两类凭据：

• MCP 凭据（mcp_oauth、static_bearer）：每个凭据以 mcp_server_url 为键。当智能体在会话运行时连接到该 URL 的服务器时，令牌会自动注入。
• 环境变量（environment_variable）：每个凭据以 secret_name（环境变量名称）为键，并以不透明占位符的形式存储在沙箱中。当智能体发起出站请求时，不透明占位符会在出口处被替换为真实的密钥值。智能体永远不会看到密钥值。对于任何通过环境变量进行身份验证的服务（例如 CLI、SDK 或直接 API 调用），请使用此类型。

您提供的实际凭据值（token、access_token、refresh_token、client_secret、secret_value）被视为敏感的只写字段，永远不会在 API 响应中返回。

凭据按提供的内容原样存储，在会话运行时之前不会进行验证。无效的凭据会在会话期间表现为身份验证错误或下游错误，该错误会被发出，但不会阻止会话继续运行。

约束条件：

• 每个保管库的键唯一。 mcp_server_url（MCP 凭据）和 secret_name（环境变量凭据）在保管库的活动凭据中必须唯一。创建重复项会返回 409。
• 键不可变。 要更改 mcp_server_url 或 secret_name，请归档该凭据并创建一个新凭据。
• 每个保管库最多 20 个凭据。



在创建会话时引用保管库

创建会话时传递 vault_ids：

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --vault-id "$VAULT_ID" \
  --title "Alice's Slack digest" \
  --transform id --raw-output)

运行时行为：

• 当没有 MCP 凭据通过 mcp_server_url 匹配时，将尝试未经身份验证的连接，如果服务器需要身份验证则会报错。
• 当多个保管库包含匹配的凭据时，第一个匹配的保管库优先。
• 在多智能体会话中，保管库凭据适用于每个线程。自身定义中声明了匹配 MCP 服务器的智能体会使用这些凭据进行身份验证。请参阅将智能体连接到 MCP 服务器。



轮换凭据

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

ant beta:vaults:credentials update \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" <<'YAML'
auth:
  type: mcp_oauth
  access_token: xoxp-new-...
  expires_at: "2099-12-31T23:59:59Z"
  refresh:
    refresh_token: xoxe-1-new-...
YAML



凭据生命周期

凭据会在会话期间和保管库生命周期内定期重新解析。这确保凭据的轮换、归档或删除能够传播到正在运行的会话，而无需重启。

要在凭据被归档、删除或刷新失败时收到通知，您可以订阅与这些生命周期变更相关的保管库和凭据 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 或网络故障）。等待后重试。

ant beta:vaults:credentials mcp-oauth-validate \
  --vault-id "$VAULT_ID" \
  --credential-id "$CREDENTIAL_ID" \
  --transform status --raw-output  # "valid", "invalid", or "unknown"

响应是一个 vault_credential_validation 对象。mcp_probe 包含失败的 MCP 握手步骤；refresh 包含尝试刷新的结果。

{
  "type": "vault_credential_validation",
  "credential_id": "vcrd_01ABC...",
  "vault_id": "vlt_01XYZ...",
  "validated_at": "2026-04-29T17:12:00Z",
  "has_refresh_token": false,
  "status": "invalid",
  "mcp_probe": {
    "method": "initialize",
    "http_response": {
      "status_code": 401,
      "content_type": "application/json",
      "body": "{\"error\":\"invalid_token\"}",
      "body_truncated": false
    }
  },
  "refresh": {
    "status": "no_refresh_token",
    "http_response": null
  }
}



其他操作

• 列出保管库或凭据： 分页返回，按最新优先排序。默认排除已归档的记录（传递 include_archived=true 以包含它们）。
• 归档保管库： POST /v1/vaults/{id}/archive。级联到所有凭据。密钥被清除；记录被保留以供审计。引用此保管库的未来会话将失败；正在运行的会话继续运行。
• 归档凭据： POST /v1/vaults/{id}/credentials/{cred_id}/archive。清除密钥负载；凭据键（mcp_server_url 或 secret_name）仍然可见，并被释放以供替换凭据使用。
• 删除保管库或凭据： 硬删除。记录不会被保留。如果您需要审计记录，请使用归档。