使用 Vaults 认证

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 可在运行时访问凭证内容

完整流程

创建 Vault

curl -X POST https://api.qoder.com/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"
}

添加 Credential

使用 static Bearer token 时，通过 nested auth 为 Vault 添加 Credential：

curl -X POST https://api.qoder.com/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/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 配置，也可以通过创建凭证直接导入。

在 Session 中使用

创建 Session 时通过 vault_ids 关联：

curl -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_xxx",
    "vault_ids": ["vault_019e5cdb9c3f71c3b6505eba937a40b4"]
  }'

Session 运行时，Agent 将自动获得 Vault 中所有 Credential 的访问权限，用于连接对应的 MCP 服务器。

参数说明

参数	类型	必填	说明
`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 密钥为只写（write-only），写入后不可读取，只能删除后重建。

建议为不同环境（开发/生产）创建独立的 Vault，避免混用凭证。

使用 Vaults 认证

核心概念

安全性

完整流程

参数说明

常见问题

下一步

启动 Session

Memory Stores

定义 Agent

Agent 工具

​核心概念

​安全性

​完整流程

​参数说明

​常见问题

​下一步

启动 Session

Memory Stores

定义 Agent

Agent 工具

核心概念

安全性

完整流程

参数说明

常见问题

下一步