概念

库是一组 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。

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

两种 Secret

两种 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

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。完整事件类型见事件参考。

归档与删除

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

与 Claude 托管智能体凭据库兼容

同一批库也可以用 Claude 托管智能体的官方 SDK 兼容接口访问（/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 自动重试。

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