使用 Vaults 认证

安全地存储凭据并注入到 Agent Session。

Agent 经常需要访问第三方服务——GitHub、Jira、数据库、自建 MCP 服务器等。Vaults 提供安全的凭证托管，让你把 Token 交给我们保管，Session 运行时按需注入，无需硬编码在代码里。

​

核心概念

概念	说明
Vault	凭证容器，可包含多个 Credential
Credential	单条凭证记录，绑定到具体 MCP 服务器 URL
protocol	MCP 通信协议。仅透出 streamable_http
type	凭证类型，当前仅支持 static_bearer
vault_ids	Session 创建时引用的 Vault ID 列表

​

安全性

• access_token永远不会在 API 响应中返回
• 凭证在服务端加密存储
• 仅关联的 Session 可在运行时访问凭证内容

​

完整流程

1. 创建 Vault

   curl -X POST https://api.qoder.com/api/v1/cloud/vaults \
     -H "Authorization: Bearer $QODER_PAT" \
     -H "Content-Type: application/json" \
     -d '{
       "display_name": "我的 GitHub 凭证",
       "credentials": [
         {
           "mcp_server_url": "https://mcp.github.com/mcp",
           "protocol": "streamable_http",
           "type": "static_bearer",
           "access_token": "ghp_xxxxxxxxxxxx"
         }
       ]
     }'
   

   响应示例：

   {
     "id": "vault_019e5cdb9c3f71c3b6505eba937a40b4",
     "type": "vault",
     "display_name": "我的 GitHub 凭证",
     "status": "active",
     "credentials": [
       {
         "id": "vcred_019e5cdb9c4f72a3b6505eba937a40c5",
         "vault_id": "vault_019e5cdb9c3f71c3b6505eba937a40b4",
         "status": "active",
         "mcp_server_url": "https://mcp.github.com/mcp",
         "protocol": "streamable_http",
         "type": "static_bearer",
         "created_at": "2026-05-18T08:00:00Z",
         "updated_at": "2026-05-18T08:00:00Z"
       }
     ],
     "metadata": {},
     "created_at": "2026-05-18T08:00:00Z",
     "updated_at": "2026-05-18T08:00:00Z"
   }
   

   注意响应中 不包含access_token 字段。

2. 追加 Credential

   一个 Vault 可以随时追加更多凭证：

   curl -X POST https://api.qoder.com/api/v1/cloud/vaults/vault_019e5cdb9c3f71c3b6505eba937a40b4/credentials \
     -H "Authorization: Bearer $QODER_PAT" \
     -H "Content-Type: application/json" \
     -d '{
       "mcp_server_url": "https://jira.example.com/mcp",
       "protocol": "streamable_http",
       "type": "static_bearer",
       "access_token": "jira_token_xxxxxxxx"
     }'
   
3. 在 Session 中使用

   创建 Session 时通过 vault_ids 关联：

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

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

​

参数说明

参数	类型	必填	说明
display_name	string	是	Vault 显示名称
credentials	array	是	凭证列表，至少包含一个凭证对象
credentials[].mcp_server_url	string	是	MCP 服务器地址
credentials[].protocol	string	是	streamable_http
credentials[].type	string	是	当前仅 static_bearer
credentials[].access_token	string	是	Bearer Token 值

​

常见问题

Q: 能否更新已有 Credential 的 Token？ A: 可以通过删除旧 Credential 并重新创建实现轮换。

Q: 一个 Session 可以关联多少个 Vault？ A: 没有硬性限制，但建议按服务分组管理，保持清晰。

Q: Token 泄露了怎么办？ A: 立即删除对应 Credential 并在第三方平台吊销 Token，然后创建新的 Credential。

Q: 我能查看已存储的 Token 吗？ A: 不能。出于安全考虑，access_token 写入后不可读取，只能删除重建。

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

​

下一步

启动 Session

管理会话生命周期。

Memory Stores

让 Agent 拥有跨 Session 的持久记忆。

定义 Agent

回顾 Agent 配置。

Agent 工具

为 Agent 配备内置、MCP 和自定义工具。