Agent 经常需要访问第三方服务——GitHub、Jira、数据库、自建 MCP 服务器等。Vaults 提供安全的凭证托管，让你把 Token 交给我们保管，Session 运行时按需注入，无需硬编码在代码里。
核心概念
| 概念 | 说明 |
|---|
| Vault | 凭证容器，可包含多个 Credential |
| Credential | 单条凭证记录，绑定到具体 MCP 服务器 URL |
auth.type | 凭证鉴权类型：static_bearer 或 mcp_oauth |
vault_ids | Session 创建时引用的 Vault ID 列表 |
安全性
access_token永远不会在 API 响应中返回token、refresh_token、client_secret 等其他密文也永远不会返回- 凭证在服务端加密存储
- 仅关联的 Session 可在运行时访问凭证内容
完整流程
1. 创建 Vault
curl -X POST https://api.qoder.com.cn/api/v1/cloud/vaults \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"display_name": "我的 GitHub 凭证",
"metadata": {}
}'
{
"id": "vault_019e5cdb9c3f71c3b6505eba937a40b4",
"type": "vault",
"display_name": "我的 GitHub 凭证",
"credentials": [],
"metadata": {},
"archived_at": null,
"created_at": "2026-05-18T08:00:00Z",
"updated_at": "2026-05-18T08:00:00Z"
}
2. 添加 Credential
使用 static Bearer token 时，通过 nested auth 为 Vault 添加 Credential：
curl -X POST https://api.qoder.com.cn/api/v1/cloud/vaults/vault_019e5cdb9c3f71c3b6505eba937a40b4/credentials \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"auth": {
"type": "static_bearer",
"mcp_server_url": "https://jira.example.com/mcp",
"token": "jira_token_xxxxxxxx"
}
}'
type: "vault_credential" 和脱敏后的 auth 对象，不包含密文。
使用 MCP OAuth 时，发起浏览器授权流程：
curl -X POST https://api.qoder.com.cn/api/v1/cloud/oauth/start \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"vault_id": "vault_019e5cdb9c3f71c3b6505eba937a40b4",
"mcp_server_url": "https://mcp.linear.app/mcp",
"client_id": "",
"client_secret": ""
}'
authorization_url。服务商跳转到 CAS callback 后，CAS 会使用 code 换取 token，并在 Vault 中创建 mcp_oauth Credential。PKCE、client registration 和 callback 行为详见发起 MCP OAuth。
如果已经持有 OAuth access token 和 refresh 配置，也可以通过创建凭证直接导入。
3. 在 Session 中使用
创建 Session 时通过 vault_ids 关联：
curl -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent": "agent_xxx",
"vault_ids": ["vault_019e5cdb9c3f71c3b6505eba937a40b4"]
}'
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|
display_name | string | 是 | Vault 显示名称 |
metadata | object | 否 | 自定义元数据 |
auth.type | string | 创建凭证时是 | static_bearer 或 mcp_oauth |
auth.mcp_server_url | string | MCP 凭证必填 | MCP 服务器地址 |
auth.token | string | static_bearer 必填 | Bearer Token 值，只写 |
auth.access_token | string | 导入 mcp_oauth 时必填 | OAuth access token，只写 |
auth.expires_at | string | 否 | OAuth access token 过期时间，RFC 3339 格式 |
auth.refresh | object | 否 | OAuth refresh 配置，详见 Vault 数据结构 |
常见问题
Q: MCP OAuth token 过期后怎么办？ A: 如果服务商返回了 refresh token，CAS 会在 MCP discovery 或执行前按需刷新 Credential。没有 refresh token 或 refresh 已失效时，需要重新发起 OAuth 授权。
Q: 能否更新已有 Credential 的 Token？ A: 可以。使用更新凭证原地轮换密钥；轮换 MCP OAuth Credential 后，可使用校验 MCP OAuth 凭证确认凭证可用。
Q: 一个 Session 可以关联多少个 Vault？ A: 没有硬性限制，但建议按服务分组管理，保持清晰。
Q: Token 泄露了怎么办？ A: 立即删除对应 Credential 并在第三方平台吊销 Token，然后创建新的 Credential。
Q: 我能查看已存储的 Token 吗？ A: 不能。出于安全考虑，credential 密文写入后不可读取，只能删除重建。
建议为不同环境（开发/生产）创建独立的 Vault，避免混用凭证。
