- 首次接入：选择凭据类型、创建凭据库、添加凭据，并在创建会话时绑定凭据库。
- 日常维护：查看凭据、完成 OAuth 授权、轮换凭据值，以及归档或删除资源。
首次接入
选择凭据类型
根据第三方服务的认证方式选择type：
mcp_oauth 和 static_bearer 使用 mcp_server_url 匹配 MCP 服务。environment_variable 使用 secret_name 匹配环境变量名。同一凭据库的活跃凭据中，用于匹配的字段不能重复。每个凭据库最多包含 20 条活跃凭据。
凭据的 type 和身份字段创建后不能修改。如需更换认证类型或匹配字段，请先归档旧凭据，再创建新凭据。
对于 environment_variable，沙箱中的环境变量是占位符，不是真实密钥。这种类型的凭据适合将凭据放入出站请求，不适合在本地校验真实密钥，或使用真实密钥计算请求签名。
创建凭据库
下面的请求创建一个凭据库，用于保存同一用户或同一业务场景的访问凭据：id 是凭据库 ID。保存它作为 VAULT_ID，后续添加凭据和绑定会话时需要使用。如果当前环境没有 jq，请从响应 JSON 中取出 id 后设置 VAULT_ID。
添加凭据
将访问凭据写入刚创建的凭据库。下面的示例添加一个固定 Bearer 凭据：your-token 替换为真实凭据值。保存响应中的 id 作为 CREDENTIAL_ID，后续查看、更新或归档这条凭据时需要使用它。
成功响应包含凭据的 id 和非敏感配置，但不会返回 token、access_token、refresh_token、client_secret 或 secret_value 对应的密钥值。
添加 OAuth 凭据
MCP 服务使用 OAuth 2.0 时，将type 设为 mcp_oauth，并提供 mcp_server_url 和 access_token。需要自动刷新时，再提供 refresh，其中 token_endpoint、client_id 和 token_endpoint_auth_type 必须一起正确配置。
添加环境变量凭据
客户端通过环境变量发送凭据时，使用secret_name 和 secret_value。可以用 networking 限制凭据可以替换到的目标主机，并用 injection_location 限制替换位置。省略 networking 时默认为 limited 加空白名单，凭据不会被替换到任何主机；必须显式配置 allowed_hosts 或将 type 设为 unrestricted 才会发生替换。
injection_location，请求头和请求体都启用替换。提供该对象但省略其中一个字段时，省略的字段为 false，例如只提供 {"header": true} 时不会替换请求体。至少要启用一个位置。
networking.allowed_hosts 只控制凭据可以替换到哪些目标主机，不能代替执行环境的网络策略。只有目标主机和执行环境都允许请求时，凭据替换才可用。
批量添加凭据
需要一次写入多条凭据时，使用批量创建接口，在items 中传入 1 到 20 条凭据，每条的字段与单条创建相同：
items 中用于匹配的字段（如 mcp_server_url）不能重复，否则返回 400；这批凭据同样计入凭据库 20 条活跃凭据的上限。成功响应的 items 按请求顺序返回创建的凭据，同样不返回凭据值。
完成 OAuth 授权
也可以通过浏览器授权添加mcp_oauth 凭据，无需手动填写 access_token；授权成功会自动创建凭据。同一 MCP 服务已有活跃凭据时发起授权会返回 409，需先归档旧凭据。创建授权会话后，将返回的 authorize_url 交给用户打开。
authorize_url，交给用户在浏览器中打开，并保存响应中的 oauth_session_id 作为 OAUTH_SESSION_ID。不提供 client 时，平台会自动注册 OAuth 客户端；使用已有客户端时，可以提供 client_id 以及授权服务器要求的其他 client 字段。
用户完成浏览器授权后，轮询授权会话状态：
pending 时继续轮询，状态为 authorized 时响应包含新凭据的 credential_id，请将它保存为 CREDENTIAL_ID。状态为 failed 时响应包含 error，应根据原因重新发起授权。平台没有立即完成授权的接口，必须通过轮询获取结果。
预检凭据覆盖情况
凭据预检接口用于确认一组 MCP 服务 URL 在凭据库中的活跃凭据覆盖情况。例如，在发起 OAuth 授权前预检，可以提前发现同一服务已有活跃凭据，避免授权请求返回 409：mcp_server_urls 传入 1 到 50 个不重复的 MCP 服务 URL；vault_ids 可选，最多 16 个凭据库 ID，省略时搜索调用方可见的所有凭据库。响应中的 coverage 按请求顺序给出每个 URL 的覆盖结果：mcp_server_url 是请求中的原始 URL，matching_vault_ids 是含有该 URL 活跃凭据的凭据库 ID 列表，空数组表示没有覆盖。匹配前每个 URL 会先规范化，无法规范化的 URL 不匹配任何凭据。只有 mcp_oauth 和 static_bearer 凭据计入覆盖，environment_variable 凭据不会出现在结果中。
创建会话时绑定凭据库
凭据库只能在创建会话时绑定，不能通过会话资源接口追加。agent_id 和 environment_id 应替换为已经创建并且有权访问的智能体，以及已构建就绪的执行环境的 ID。
resources 中包含 type 为 vault 的绑定。一个会话最多绑定 16 个凭据库。如果多个凭据库有同一个 MCP 服务的活跃凭据，平台按 resources 中凭据库的顺序使用第一个匹配项。
日常维护
查看凭据库和凭据
查看凭据库及其中的凭据，确认当前名称、匹配字段和归档状态。凭据列表默认不包含已归档凭据，传入include_archived=true 时，列表会同时包含已归档凭据。列表结果使用 page_size 和不透明的 page_token 分页：将响应中的 next_page_token 作为下一页请求的 page_token；该字段省略时表示没有更多结果。
更新凭据库
更新凭据库时只能修改display_name 或 metadata：
轮换凭据值
轮换凭据值时，只需提交需要更新的字段。凭据的类型和身份匹配字段不能修改，例如type、mcp_server_url、secret_name、token_endpoint 和 client_id。请求中的 type 必须与现有凭据一致。
下面的请求轮换一个静态 Bearer 凭据的令牌。mcp_server_url 是该凭据已有的值，不能改成其他地址：
归档或删除
归档和删除是两种不同的操作：- 归档：保留资源记录，清除其中的密钥值。归档后的凭据或凭据库不能用于新会话。
- 删除：永久删除资源记录。
归档凭据库时，其中的活跃凭据也会被归档并清除密钥值。删除凭据库时，其中的凭据记录也会一并删除，不需要再单独删除。
归档一条凭据，保留凭据记录：
安全边界
凭据值只接受写入，不会出现在创建、查询、列表或更新响应中。不要在客户端日志、提示词或其他会进入模型上下文的内容中记录凭据值。 MCP 凭据按mcp_server_url 匹配，环境变量凭据按 secret_name 匹配。对于 environment_variable，只有目标主机和执行环境的网络策略都允许请求时，平台才会替换占位符。