> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed Secrets HTTP 契约

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，不含值或加密封装。

```sh theme={null}
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" "$HEXAGON_API_URL/v1/secrets"
```

`GET /v1/secrets/{id}` 返回 **200**，上述字段之外增加：

| 字段 | 内容与范围 |
| - | - |
| connections | 未删除的直接引用，每项 id/name/kind，按 ID 排列 |
| harnesses | 注册镜像引用，每项 id/version，按 ID/version 排列 |
| sessions | 最多 200 条 Session/连接行，最新 Session 在前；字段 id、state、name、connection\_id、connection\_name、kind、revoked\_at |

Session 引用基于固定连接 ID 和当前 managed-secret 关联，不是完整历史凭据审计。一个 Session 可因不同连接出现多次，closed Session 也不排除。该数组有上限但没有下一页游标，不能据此证明不存在其他依赖。

```sh theme={null}
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" "$HEXAGON_API_URL/v1/secrets/$HEXAGON_SECRET_ID"
```

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，然后执行：

```sh theme={null}
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @secret-create.json "$HEXAGON_API_URL/v1/secrets"
```

响应丢失时先检查元数据，再决定是否创建另一项。此接口族没有恢复明文的端点。

## 更新与轮换

`PATCH /v1/secrets/{id}` 接受严格对象，可选 name、value、enabled:boolean；name/value 沿用创建限制。成功返回 **200** 和当前详情。省略字段保留原值。没有 expected\_version 条件；行锁串行化修改，但不会检测客户端意图已过期。

| 提供的变更 | 效果 |
| - | - |
| 只提供 name | 修改名称并递增 Secret 版本，关联连接不变 |
| 提供 value | 替换加密值，更新未删除关联连接的凭据副本并使其失效 |
| 提供 enabled | 按输入更新或保留布尔值；即使值未变，也使关联连接失效 |
| 空对象 | 接受，并递增 Secret 版本、更新 updated\_at |

连接失效意味着 enabled=false、status=draft、validation=null，并递增连接版本。重新启用 Secret 不会自动验证或启用连接。更新覆盖未删除的 managed-secret 连接引用，不改写固定的 Session 定义；既有访问可能因可用性或版本检查失败，需要安排重新验证和后续 Session 使用。

以下请求禁用 Secret，并使关联连接失效：

```sh theme={null}
curl --fail-with-body --silent --show-error --request PATCH \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" -H 'Content-Type: application/json' \
  --data '{"enabled":false}' "$HEXAGON_API_URL/v1/secrets/$HEXAGON_SECRET_ID"
```

轮换值时使用含新值的私有请求文件，不将值放入命令。重复 PATCH 不是无害幂等重放，会递增版本并可能再次使连接失效。响应丢失后先检查版本和就绪状态，再决定重试。控制平面更新成功不代表外部 Provider 的旧凭据已经撤销。

## 删除

`DELETE /v1/secrets/{id}` 返回 **204**，无响应体。任何未删除连接或注册 Harness 镜像引用都会导致 `409 secret_in_use`。仅禁用不会解除引用；先检查依赖，并通过其支持的生命周期操作处理。

```sh theme={null}
curl --fail-with-body --silent --show-error --request DELETE \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  "$HEXAGON_API_URL/v1/secrets/$HEXAGON_SECRET_ID"
```

删除是软删除：设置 deleted\_at、禁用、递增版本，不承诺物理擦除全部加密历史或在 Provider 撤销凭据。之后 GET 或重复 DELETE 返回 `404 secret_not_found`；响应丢失时结合已记录资源身份与当前租户查询结果对账。

严格输入无效返回 `400 invalid_request`；应用 Token 返回 `403 owner_token_required`；未认证返回 401。这些操作本身不向 Provider 验证凭据。来源：[Managed Secret 实现](https://github.com/NexusFox88/docs/blob/main/resources/modules/credentials/managed-secrets.ts)、[HTTP 路由](https://github.com/NexusFox88/docs/blob/main/resources/apps/control-plane/server.ts)。[凭据契约审阅](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-20-credential-http-contract-review.json)在独立租户中使用虚拟值和真实 PostgreSQL 加密存储，验证了创建/读取/列表/修改/删除、空 patch 递增版本、仅改名不改变连接状态、值轮换更新受保护副本并使受控连接失效、重复 enabled 仍触发失效、依赖删除拒绝、租户与角色边界，以及响应不含明文。测试行已清理，没有轮换外部真实凭据；本次未执行 Harness 镜像依赖分支或最多 200 行的 Session 引用查询场景。

## 修改后读取版本

假设新 Secret 为版本 1，提交 `{}` 后返回版本 2，即使可见名称与 enabled 状态没有变化。随后仅改名返回版本 3，引用连接的版本不变；再修改 value 返回版本 4，并递增每个未删除引用连接的版本，同时禁用连接、清除验证。这里的数字表示没有其他编辑介入的一条顺序；实际应用应读取返回值。

不要仅根据名称或 enabled 判断丢失响应的 patch 是否已提交。保存变更前版本和操作意图，检查当前或返回的 Secret 及受影响连接，再决定后续更新。此端点没有 compare-and-swap 前置条件，另一个编辑者可能在你的读取和写入之间改变记录。

下一步：[凭据轮换指南](https://docs.hexagon.autos/zh-CN/operate/credentials.md)、[HTTP 总览](https://docs.hexagon.autos/zh-CN/reference/http.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.