/v1。不要将真实 Secret 放入命令历史、共享 JSON fixture 或公开证据。含值请求文件应存于私有位置,不再需要时移除明文副本。
元数据与引用
GET /v1/secrets 返回 200、{secrets:[...]},按创建时间升序,无分页,排除已删除项。每项包含 id、name、version、enabled、created_at、updated_at,不含值或加密封装。
GET /v1/secrets/{id} 返回 200,上述字段之外增加:
Session 引用基于固定连接 ID 和当前 managed-secret 关联,不是完整历史凭据审计。一个 Session 可因不同连接出现多次,closed Session 也不排除。该数组有上限但没有下一页游标,不能据此证明不存在其他依赖。
404 secret_not_found。
创建
POST /v1/secrets 接受严格 {name,value}。Name 必填,1–200 字符;value 必填,1–32,768 字符且不含 NUL。下游凭据协议可能有额外限制。此 schema 不对名称做 trim。
成功返回 201 和上述元数据/详情对象,不返回输入明文。创建事务使用已配置 SecretStore 保存。Name 不是幂等键,重复 POST 可创建不同 Secret。
私有准备包含真实 name/value 的 secret-create.json,然后执行:
更新与轮换
PATCH /v1/secrets/{id} 接受严格对象,可选 name、value、enabled:boolean;name/value 沿用创建限制。成功返回 200 和当前详情。省略字段保留原值。没有 expected_version 条件;行锁串行化修改,但不会检测客户端意图已过期。
连接失效意味着 enabled=false、status=draft、validation=null,并递增连接版本。重新启用 Secret 不会自动验证或启用连接。更新覆盖未删除的 managed-secret 连接引用,不改写固定的 Session 定义;既有访问可能因可用性或版本检查失败,需要安排重新验证和后续 Session 使用。
以下请求禁用 Secret,并使关联连接失效:
删除
DELETE /v1/secrets/{id} 返回 204,无响应体。任何未删除连接或注册 Harness 镜像引用都会导致 409 secret_in_use。仅禁用不会解除引用;先检查依赖,并通过其支持的生命周期操作处理。
404 secret_not_found;响应丢失时结合已记录资源身份与当前租户查询结果对账。
严格输入无效返回 400 invalid_request;应用 Token 返回 403 owner_token_required;未认证返回 401。这些操作本身不向 Provider 验证凭据。来源:Managed Secret 实现、HTTP 路由。凭据契约审阅在独立租户中使用虚拟值和真实 PostgreSQL 加密存储,验证了创建/读取/列表/修改/删除、空 patch 递增版本、仅改名不改变连接状态、值轮换更新受保护副本并使受控连接失效、重复 enabled 仍触发失效、依赖删除拒绝、租户与角色边界,以及响应不含明文。测试行已清理,没有轮换外部真实凭据;本次未执行 Harness 镜像依赖分支或最多 200 行的 Session 引用查询场景。
修改后读取版本
假设新 Secret 为版本 1,提交{} 后返回版本 2,即使可见名称与 enabled 状态没有变化。随后仅改名返回版本 3,引用连接的版本不变;再修改 value 返回版本 4,并递增每个未删除引用连接的版本,同时禁用连接、清除验证。这里的数字表示没有其他编辑介入的一条顺序;实际应用应读取返回值。
不要仅根据名称或 enabled 判断丢失响应的 patch 是否已提交。保存变更前版本和操作意图,检查当前或返回的 Secret 及受影响连接,再决定后续更新。此端点没有 compare-and-swap 前置条件,另一个编辑者可能在你的读取和写入之间改变记录。
下一步:凭据轮换指南、HTTP 总览。