凭据管理

Vault 是凭据的集合：你把 MCP 服务器的 token、OAuth 凭据或环境变量密钥注册进 Vault，创建会话时通过 vault_ids 引用。密钥只写不读——所有 token、secret 在任何响应中都不会回显，Agent 与沙箱也拿不到原始值。

创建 Vault

vault=$(curl -sS "$BASE_URL/v1/vaults" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d '{
    "display_name": "Production credentials"
  }')

VAULT_ID=$(jq -r '.id' <<< "$vault")

字段：display_name（必填，1–255 字符）、metadata（可选，最多 16 个 string 键值）。

添加凭据

POST /v1/vaults/:vaultId/credentials 创建凭据。auth 是按 type 区分的鉴权对象，支持五种类型：

类型	用途	身份键（不可变）
static_bearer	MCP 服务器的静态 Bearer token	mcp_server_url
mcp_oauth	MCP 服务器的 OAuth（支持自动刷新）	mcp_server_url
bearer	普通 HTTPS origin 的静态 Bearer	host
oauth	普通 HTTPS origin 的 OAuth	host
environment_variable	以环境变量形式注入沙箱的密钥	secret_name

curl -sS "$BASE_URL/v1/vaults/$VAULT_ID/credentials" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d '{
    "display_name": "GitHub MCP token",
    "auth": {
      "type": "static_bearer",
      "mcp_server_url": "https://api.githubcopilot.com/mcp/",
      "token": "ghp_xxxxxxxxxxxx"
    }
  }'

curl -sS "$BASE_URL/v1/vaults/$VAULT_ID/credentials" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d '{
    "auth": {
      "type": "mcp_oauth",
      "mcp_server_url": "https://mcp.example.com/",
      "access_token": "at_xxxxxxxx",
      "expires_at": "2026-09-01T00:00:00Z",
      "refresh": {
        "token_endpoint": "https://auth.example.com/oauth/token",
        "client_id": "my-client",
        "refresh_token": "rt_xxxxxxxx",
        "token_endpoint_auth": {
          "type": "client_secret_basic",
          "client_secret": "cs_xxxxxxxx"
        }
      }
    }
  }'

OAuth 类型的要点：access_token 必填；配置了 refresh 后平台会在过期前用 refresh_token 自动换新。token_endpoint_auth.type 支持 none / client_secret_basic / client_secret_post（none 仅创建时接受）。

curl -sS "$BASE_URL/v1/vaults/$VAULT_ID/credentials" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d '{
    "auth": {
      "type": "environment_variable",
      "secret_name": "EXAMPLE_API_KEY",
      "secret_value": "sk-xxxxxxxx",
      "networking": {
        "type": "limited",
        "allowed_hosts": ["api.example.com"]
      }
    }
  }'

environment_variable 类型必须声明 networking 策略（unrestricted，或 limited + allowed_hosts，至多 16 项，支持 *.example.com 通配），限定携带该密钥的出站请求能到达哪些主机。

在创建会话时引用

创建会话时传 vault_ids（最多 20 个、不重复，顺序即匹配优先级）。MCP 凭据按 mcp_server_url 与 Agent 声明的服务器 URL 匹配；无匹配凭据的服务器以未认证方式连接。详见连接 MCP。

验证 MCP OAuth

不必等到会话里才发现凭据失效。mcp_oauth_validate 会向目标服务器发起 MCP initialize 探测：

curl -sS -X POST "$BASE_URL/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID/mcp_oauth_validate" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26"

响应包含：status（valid / invalid / unknown 综合结论）、mcp_probe（initialize 探测的 HTTP 摘要，敏感值已脱敏）、refresh（刷新尝试结果：succeeded / failed / connect_error / no_refresh_token）、has_refresh_token（是否配置了 refresh token，不泄露其值）。

轮换凭据

POST /v1/vaults/:vaultId/credentials/:credentialId 做部分更新：提供的 secret 被替换，省略的 secret 保留。身份字段（mcp_server_url / host / secret_name，以及 refresh 的 token_endpoint / client_id / resource）不可变，更新时必须省略——要换目标就新建一条凭据。

curl -sS "$BASE_URL/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID" \
  -H "Authorization: Bearer $ZHIPUAI_API_KEY" \
  -H "zai-version: 2026-05-26" \
  -H "zai-beta: managed-agents-2026-05-26" \
  -H "content-type: application/json" \
  -d '{
    "auth": {
      "type": "static_bearer",
      "token": "ghp_new_token_xxxx"
    }
  }'

auth.type 必须与原凭据相同。OAuth 凭据可分别轮换 access_token、refresh_token、client_secret，或用 refresh: null 清除刷新配置。

凭据生命周期与其他操作

接口	说明
GET /v1/vaults · GET /v1/vaults/:id	列出 / 获取 Vault（include_archived 可选）
POST /v1/vaults/:id	更新 display_name / metadata
POST /v1/vaults/:id/archive · DELETE /v1/vaults/:id	归档 / 删除 Vault
GET /v1/vaults/:id/credentials · GET …/credentials/:cid	列出 / 获取凭据（仅非敏感字段）
POST …/credentials/:cid/archive · DELETE …/credentials/:cid	归档 / 删除凭据

读取接口只返回非敏感字段：凭据的 token / secret / client_secret 永不回显；OAuth 凭据回显 expires_at 与不含秘密值的 refresh 配置。

安全边界

密钥只写不读：创建和轮换时提交的 token / secret 不会出现在任何 API 响应里。
Agent 与沙箱拿不到凭据原文；MCP 与 HTTPS 出站由平台侧注入，不进入提示词或进程环境。
environment_variable 类型会按你声明的 networking 限制出站主机，见上文。
会话创建前可用 mcp_oauth_validate 探测 MCP OAuth 是否仍有效，不必等到会话里才发现失败。

下一步

连接 MCP

凭据与 MCP 服务器的匹配规则

创建会话

vault_ids 的使用

本页对应 OpenAPI

Vault：凭据创建、轮换、验证 MCP OAuth

开始使用

定义 Agent

配置运行环境

运行会话

上下文与记忆

自动化

参考

创建 Vault

添加凭据

在创建会话时引用

验证 MCP OAuth

轮换凭据

凭据生命周期与其他操作

安全边界

下一步

连接 MCP

创建会话

本页对应 OpenAPI

​创建 Vault

​添加凭据

​在创建会话时引用

​验证 MCP OAuth

​轮换凭据

​凭据生命周期与其他操作

​安全边界

​下一步

连接 MCP

创建会话

本页对应 OpenAPI

创建 Vault

添加凭据

在创建会话时引用

验证 MCP OAuth

轮换凭据

凭据生命周期与其他操作

安全边界

下一步