跳转到主要内容
Managed Secrets 在控制平面保存可复用的凭据值。五个路由均要求 owner 身份和租户归属,不通过读取响应暴露已保存明文。普通 Session 变量用于允许 Agent 进程读取的值,与本机制不同。 示例使用 HEXAGON_API_TOKEN 中的后端 owner Token,HEXAGON_API_URL 不包含 /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 也不排除。该数组有上限但没有下一页游标,不能据此证明不存在其他依赖。
Secret 不存在、已删除或属于其他租户返回 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,并使关联连接失效:
轮换值时使用含新值的私有请求文件,不将值放入命令。重复 PATCH 不是无害幂等重放,会递增版本并可能再次使连接失效。响应丢失后先检查版本和就绪状态,再决定重试。控制平面更新成功不代表外部 Provider 的旧凭据已经撤销。

删除

DELETE /v1/secrets/{id} 返回 204,无响应体。任何未删除连接或注册 Harness 镜像引用都会导致 409 secret_in_use。仅禁用不会解除引用;先检查依赖,并通过其支持的生命周期操作处理。
删除是软删除:设置 deleted_at、禁用、递增版本,不承诺物理擦除全部加密历史或在 Provider 撤销凭据。之后 GET 或重复 DELETE 返回 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 总览。