> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Vaults 认证

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

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

## 核心概念

| 概念          | 说明                                                          |
| ----------- | ----------------------------------------------------------- |
| Vault       | 凭证容器，可包含多个 Credential                                       |
| Credential  | 单条凭证记录，绑定到具体 MCP 服务器 URL                                    |
| `auth.type` | 凭证鉴权类型：`static_bearer`、`mcp_oauth` 或 `environment_variable` |
| `vault_ids` | Session 创建时引用的 Vault ID 列表                                  |

## 安全性

* `access_token`**永远不会**在 API 响应中返回
* `token`、`refresh_token`、`client_secret`、`secret_value` 等其他密文也永远不会返回
* 凭证在服务端加密存储
* 仅关联的 Session 可在运行时访问凭证内容

## 完整流程

<Steps>
  <Step title="创建 Vault">
    ```bash theme={null}
    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 凭证",
        "metadata": {}
      }'
    ```

    响应示例：

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="追加 Credential">
    使用 nested `auth` 对象为 Vault 追加凭证：

    ```bash theme={null}
    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 '{
        "auth": {
          "type": "static_bearer",
          "mcp_server_url": "https://jira.example.com/mcp",
          "token": "jira_token_xxxxxxxx"
        }
      }'
    ```

    响应返回 `type: "vault_credential"` 和经过脱敏的 `auth` 对象，不包含任何密钥明文。
  </Step>

  <Step title="在 Session 中使用">
    创建 Session 时通过 `vault_ids` 关联：

    ```bash theme={null}
    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 服务器。
  </Step>
</Steps>

## 参数说明

| 参数                    | 类型     | 必填                 | 说明                                                   |
| --------------------- | ------ | ------------------ | ---------------------------------------------------- |
| `display_name`        | string | 是                  | Vault 显示名称                                           |
| `metadata`            | object | 否                  | 自定义元数据                                               |
| `auth.type`           | string | 创建凭证时必选            | `static_bearer`、`mcp_oauth` 或 `environment_variable` |
| `auth.mcp_server_url` | string | MCP 凭证必填           | MCP 服务器地址                                            |
| `auth.token`          | string | `static_bearer` 必填 | Bearer Token 值，只写                                    |

## 常见问题

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

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

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

**Q: 我能查看已存储的 Token 吗？** A: 不能。出于安全考虑，credential 密钥为只写（write-only），写入后不可读取，只能删除后重建。

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

## 下一步

<CardGroup cols={2}>
  <Card title="启动 Session" icon="play" href="/zh/cloud-agents/sessions">
    管理会话生命周期。
  </Card>

  <Card title="Memory Stores" icon="brain" href="/zh/cloud-agents/memory-stores">
    让 Agent 拥有跨 Session 的持久记忆。
  </Card>

  <Card title="定义 Agent" icon="user-gear" href="/zh/cloud-agents/define-agent">
    回顾 Agent 配置。
  </Card>

  <Card title="Agent 工具" icon="wrench" href="/zh/cloud-agents/tools">
    为 Agent 配备内置、MCP 和自定义工具。
  </Card>
</CardGroup>