# 概念 (/docs/cloud/services/vault/concepts)



库是一组 Secret；Secret 是一个凭据，由名字、值和允许的域名组成。其余功能都只是产生或更新 Secret 的方式。

## 库与 Secret [#库与-secret]

API Key 决定你能访问哪些库。库有显示名称和最多 16 对 metadata 标签。

Secret 的名字在库内唯一，创建后不能修改，只能使用大写字母、数字和下划线，长度为 1–128 个字符，可以以下划线开头，但不能以数字开头，例如 `GITHUB_TOKEN`。可以用名字或 `vsec_` 开头的 ID 寻址一个 Secret；非法名称查找也返回 404 `SECRET_NOT_FOUND`。

值只写：创建或替换后，任何接口都不再返回它。每次替换值，`version` 加一。

## 允许的域名 [#允许的域名]

每个 Secret 必须声明 `allowed_hosts`，1–16 个；空数组返回 400 `INVALID_PARAMS`。只有发往这些域名的请求才能用到这个 Secret。

| 写法               | 匹配                                           |
| ---------------- | -------------------------------------------- |
| `api.github.com` | 只匹配这个域名                                      |
| `*.example.com`  | 匹配 `example.com` 的任意子域名，不匹配 `example.com` 本身 |
| `192.0.2.1`      | 只匹配这个 IPv4 地址                                |

域名写入时统一转为小写，去掉末尾的点，国际化域名转为 punycode。重复项会去重。不提供“任意域名”。IPv6、单标签主机（包括 `localhost`）、`*.internal`、平台域名，以及回环、链路本地、私网与 CGNAT IPv4 均返回 400 `INVALID_PARAMS`。

## 两种 Secret [#两种-secret]

| kind     | 值从哪来              | 状态                                     |
| -------- | ----------------- | -------------------------------------- |
| `static` | 你填写的值             | `active`                               |
| `oauth`  | 一键授权得到的访问令牌，由平台续期 | `active`、`refreshing`、`refresh_failed` |

两种 Secret 归档后状态都是 `archived`。

## 模板 [#模板]

模板为常用服务预填名字、允许的域名和种类，你只需填写值。`GET /vault/v1/templates` 列出全部模板，static 模板有 `github`、`openai`、`anthropic`、`stripe`，OAuth 模板有 `linear`、`atlassian`。GitHub 预填 `GITHUB_TOKEN` 和 `api.github.com`、`uploads.github.com`。添加 static Secret 时可传 `template_id`，其来源记录为 `metadata.template`。

`metadata.source` 和 `metadata.template` 是系统保留键，调用方不能写入，也不占自定义标签的 16 对限额。更新库或 Secret 的 metadata 按键合并：字符串写入，`null` 删除该键，省略的键保留。Secret 的 `description: null` 清除备注，省略则保留。

## 导入 .env [#导入-env]

`POST /vault/v1/vaults/{vault_id}/secrets:import` 一次创建多个 static Secret。传 `dotenv`（`KEY=VALUE` 多行文本）或 `lines` 数组，二者选一；新建时，`allowed_hosts` 默认值应用到没有自带域名的行。同名 Secret 只替换值，只有该行自身的 `allowed_hosts` 才会改变原域名，顶层默认域名不会覆盖原域名。结果分别列出新建、替换和失败的行，失败行带行号与错误码，其余行照常写入。

## 一键授权 [#一键授权]

Linear（CIMD：客户端元数据文档）和 Atlassian（DCR：动态客户端注册）可以通过一键授权产生 `oauth` Secret，无需事先注册应用。需要应用注册的服务（GitHub、HubSpot、Asana、Vercel）请手动添加凭据；Asana 不在一键授权模板中。

1. 调用 `POST /vault/v1/authorizations`，传支持授权的 `template_id`，或要授权的 `resource_url`。
2. 把返回的 `connect_url` 交给最终用户。这个链接 30 分钟内有效、只能使用一次。
3. 用户在确认页看到发起方、目标服务和申请的权限，同意后跳转到服务方完成授权。
4. 完成后，库中出现名为 `secret_name` 的 `oauth` Secret。读取 `GET /vault/v1/authorizations/{id}` 可查看状态：`pending`、`authorizing`、`completed`、`failed` 或 `expired`。

库中已有同名 Secret 时，授权会原地更新它：ID 不变，`version` 加一。

需要授权后回到你的应用时，传 `return_url`。它必须在回跳地址白名单内：用 `PUT /vault/v1/settings/return_urls` 设置，最多 10 个 https 地址，精确匹配。回跳时会带上 `authorization_id` 和 `status`。

## 续期与校验 [#续期与校验]

`oauth` Secret 的访问令牌由平台在过期前续期。服务方拒绝续期时，Secret 变为 `refresh_failed`，`oauth.last_error` 说明原因；重新授权或替换值后恢复为 `active`。服务方暂时不可用时，Secret 保持 `active` 并稍后重试。

`POST …/secrets/{secret}/validate` 用当前令牌向服务发一次探测，返回 `valid`、`invalid` 或 `unknown`，只适用于 `oauth` Secret。调用方收到服务的 401 后，可以调用 `POST …/secrets/{secret}/refresh` 立即续期；同样仅支持 `oauth` Secret。对 static Secret 校验返回 400 `VALIDATE_UNSUPPORTED`，续期返回 400 `SECRET_KIND_MISMATCH`。

## 审计事件 [#审计事件]

库的事件记录创建、更新、归档、删除、使用、续期和授权结果，不包含 Secret 的值。`GET /vault/v1/vaults/{vault_id}/events` 按时间倒序列出，可用 `secret` 按名称或 ID 过滤；未知 Secret 返回空列表。更新事件的 `detail.changed` 列出修改的字段，例如 `value`、`allowed_hosts`。

事件没有按天自动过期的保留期；归档保留事件，删除库或 Secret 会清除其历史事件，仅留下删除记录。`limit` 默认 50、最大 200；超限或无效 `cursor` 返回 400 `INVALID_PARAMS`。完整事件类型见[事件参考](/docs/api/native/vault/vaults)。

## 归档与删除 [#归档与删除]

归档库会同时归档库内全部 Secret 并清除它们的值，之后不能再写入。删除库会删除全部 Secret，不可恢复。单个 Secret 同样可以归档或删除。

## 与 Claude 托管智能体凭据库兼容 [#与-claude-托管智能体凭据库兼容]

同一批库也可以用 Claude 托管智能体的[官方 SDK 兼容接口](/docs/api/compatible/anthropic/managed-agents)访问（`/anthropic/v1/vaults`）。每个请求需要 API Key、`anthropic-version: 2023-06-01`，以及包含 `managed-agents-2026-04-01` 的 `anthropic-beta`；该头可用逗号分隔包含其它 beta。列表使用 `page` 而非 `cursor` 分页；凭据只能用 `vsec_` ID 寻址。库的 `display_name: null` 返回 400。

错误体为 `{type: "error", error: {type, message}, request_id}`；409 对应 `conflict_error`。409 等不可重试错误带 `x-should-retry: false`，不会触发 SDK 自动重试。

| 凭据类型                   | 对应的 Secret                                                                     |
| ---------------------- | ------------------------------------------------------------------------------ |
| `environment_variable` | 名字为 `secret_name`，允许的域名为 `networking.allowed_hosts`；`networking` 只支持 `limited` |
| `static_bearer`        | 允许的域名为 `mcp_server_url` 的主机，名字自动生成为 `MCP_<主机>`                                 |
| `mcp_oauth`            | 暂不支持创建，返回 501；请改用一键授权                                                          |

通过 `/vault/v1` 创建的 Secret 在该接口中显示为 `environment_variable`，`injection_location` 为只在请求头中替换。