> ## 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.

# Vault 数据结构

> Vault 与 credential 的复用结构。

## Vault 对象

创建、查询、列表和归档接口都会返回该结构。

| 字段             | 类型                                       | 说明                                                                  |
| -------------- | ---------------------------------------- | ------------------------------------------------------------------- |
| `id`           | string                                   | Vault ID，前缀为 `vault_`                                               |
| `type`         | string                                   | 固定值 `"vault"`                                                       |
| `display_name` | string                                   | Vault 展示名称，最长 255 字符                                                |
| `metadata`     | object                                   | [Metadata 对象](/zh/cloud-agents/api/conventions/schemas#metadata-对象) |
| `credentials`  | [Vault credential](#vault-credential) 数组 | 仅创建 Vault 的响应中返回，值固定为空数组；凭证通过独立的 credential 接口管理                    |
| `archived_at`  | string \| null                           | 归档时间；active 时为 `null`                                               |
| `created_at`   | string                                   | 创建时间                                                                |
| `updated_at`   | string                                   | 最后更新时间                                                              |

## Vault credential

创建 credential、列表 credential 和归档 credential 接口会返回该结构。

| 字段             | 类型                                                | 说明                                   |
| -------------- | ------------------------------------------------- | ------------------------------------ |
| `id`           | string                                            | Credential ID，前缀为 `vcred_`           |
| `type`         | string                                            | 固定值 `"vault_credential"`             |
| `vault_id`     | string                                            | 所属 Vault ID                          |
| `auth`         | [Credential auth object](#credential-auth-object) | 脱敏后的鉴权信息；不会返回密文                      |
| `display_name` | null                                              | 当前固定为 `null`                         |
| `metadata`     | object                                            | 与 credential 一起存储的自定义元数据对象；省略时为 `{}` |
| `archived_at`  | string \| null                                    | 归档时间；active 时为 `null`                |
| `created_at`   | string                                            | 创建时间                                 |
| `updated_at`   | string                                            | 最后更新时间                               |

Credential 密文（包括 `token`、`access_token`、`refresh_token`、`client_secret` 和 `secret_value`）只在创建请求中接收，永远不会在响应中返回。

## 创建 credential 请求

| 字段             | 类型     | 必填 | 说明                                   |
| -------------- | ------ | -- | ------------------------------------ |
| `auth`         | object | 是  | 凭证鉴权信息                               |
| `display_name` | string | 否  | 兼容字段；当前响应固定为 `null`，不持久化             |
| `metadata`     | object | 否  | 与 credential 一起存储的自定义元数据对象；省略时为 `{}` |

## Credential auth object

### `static_bearer`

| 字段               | 类型     | 必填 | 说明                               |
| ---------------- | ------ | -- | -------------------------------- |
| `type`           | string | 是  | `static_bearer`                  |
| `mcp_server_url` | string | 是  | MCP server URL，最长 2048 字符        |
| `token`          | string | 是  | 安全存储在 Vault 中的 Bearer token；不会返回 |

响应中的 auth 会省略 `token`。

### `mcp_oauth`

| 字段               | 类型     | 必填 | 说明                                            |
| ---------------- | ------ | -- | --------------------------------------------- |
| `type`           | string | 是  | `mcp_oauth`                                   |
| `mcp_server_url` | string | 是  | MCP server URL，最长 2048 字符                     |
| `access_token`   | string | 是  | OAuth access token；不会返回                       |
| `expires_at`     | string | 否  | Access token 过期时间，RFC 3339 格式                 |
| `refresh`        | object | 否  | 刷新配置。响应中会去除 `refresh_token` 和 `client_secret` |

### `environment_variable`

| 字段             | 类型     | 必填 | 说明                                  |
| -------------- | ------ | -- | ----------------------------------- |
| `type`         | string | 是  | `environment_variable`              |
| `secret_name`  | string | 是  | 环境变量名，必须匹配 `[A-Za-z_][A-Za-z0-9_]*` |
| `secret_value` | string | 是  | Secret 值；不会返回                       |
| `networking`   | object | 否  | 兼容字段；当前不执行，响应中为空对象                  |