> ## 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.

# 应用 Token HTTP 契约

应用 Token 用于可信应用后端执行已配置任务，管理 Token 要求 owner 身份。这些接口不会创建租户、轮换 owner 凭据或赋予任意自定义 scope。Application 角色采用服务端路由白名单，应用仍须对自己的用户和业务资源做授权。

以下路由均位于 `/v1`。认证缺失、过期或撤销返回 `401 unauthorized`；application 身份尝试管理 Token 返回 `403 owner_token_required`。示例的 HEXAGON\_API\_TOKEN 必须是 owner Token，HEXAGON\_API\_URL 不包含 `/v1`。不要开启 shell 跟踪或将含 Token 的响应放入公共日志。

## 列出元数据

`GET /v1/tokens` 返回 **200** 和 `{tokens:[...]}`，按创建时间倒序，无分页参数。每项包含 id、label、role、expires\_at、last\_used\_at、revoked\_at、created\_at；历史记录的可选时间可能为 null。列表包括本租户 owner 和 application 行，也包括过期或撤销项，不返回明文 Token 或摘要。

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

认证接受 API key 时会更新 last\_used\_at。该时间不是逐请求审计日志，也不能证明某项下游操作完成。

## 创建应用 Token

`POST /v1/tokens` 接受严格 JSON 对象：

| 字段 | 限制 |
| - | - |
| label | 必填字符串，先 trim，再检查 1–200 字符 |
| expires\_in\_days | 可选 1–365 整数，默认 30 |

成功返回 **201**；包含 id、label、role:application、expires\_at、created\_at、token，响应头为 Cache-Control:no-store。生成值以 hx\_app\_ 开头，服务端存储 SHA-256 摘要。本次响应是取得明文值的机会，列表接口不能恢复明文。

请在新的私有目录执行。以下命令会创建凭据，并将完整响应保存到私有文件：

```sh theme={null}
umask 077
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" -H 'Content-Type: application/json' \
  --data '{"label":"Project backend","expires_in_days":30}' \
  --output application-token-created.json \
  "$HEXAGON_API_URL/v1/tokens"
```

必须确认退出码为 0 后再将响应当成凭据读取，错误响应也可能写入输出文件。将 Token 转移到后端的 Secret 存储。Label 和重复创建请求都不去重。响应丢失后检查列表，确定新建项并撤销确认不使用的 Token，再明确创建替代项；不要自动循环重试 POST。

## 轮换应用 Token

`POST /v1/tokens/{id}/rotate` 无必需请求体，返回 **200**，字段与创建一致，并包含 Cache-Control:no-store。

```sh theme={null}
umask 077
curl --fail-with-body --silent --show-error --request POST \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  --output application-token-rotated.json \
  "$HEXAGON_API_URL/v1/tokens/$HEXAGON_TOKEN_ID/rotate"
```

事务要求目标为当前租户未撤销、未过期的 application Token。它撤销原行，插入新的 ID/Token，保留 label 和**原到期时间**，不会延长有效期。没有旧新并存的宽限期；轮换事务提交后，旧 Token 不能再通过新的认证，因此需要安排后端 Secret 更新。

对旧 ID 重复轮换返回 `404 application_token_not_found`，不能找回丢失的替代明文。目标不存在、属于其他租户、为 owner、已过期或已撤销也返回此错误。响应丢失时用 owner 列表调查，撤销能明确识别但无法使用的替代项，再主动签发其他 Token；不能因为响应丢失就假定旧 Token 仍有效。撤销不会收回已经通过认证的请求，也不会取消其 Run。

## 撤销应用 Token

`DELETE /v1/tokens/{id}` 返回 **200**、`{id,revoked_at}`，是 JSON 响应，不是 204。

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

重复撤销同一 application 行会成功，并保留首次 revoked\_at 时间。已经过期的 application 行也可撤销。目标不存在、属于其他租户或为 owner 时返回 `404 application_token_not_found`。记录仍保留在元数据列表中，owner 也不能通过此接口撤销 owner key。

这些路径 ID 按字符串解析，路由没有 UUID 校验；实际生成的 application ID 是 UUID。创建请求结构不合法或包含未知属性返回 `400 invalid_request`。创建、轮换和撤销的重复请求语义不同，此处只有撤销自然支持重复动作。

## 角色边界与核对

Application Token 可以使用允许的任务路由，包括创建 Session、提交/观察/取消 Run、下载产物、创建/撤销预览或 access，以及部分 Agent/catalog/connection 读取。它不能管理凭据、作出审批决定或确认未知 Tool 结果。精确路由分类由 [HTTP 总览](https://docs.hexagon.autos/zh-CN/reference/http.md)生成；路由匹配仍须通过归属、参数和状态校验。

安装替代凭据后，使用它执行一个允许的读取，并确认旧凭据的新请求返回 401。Owner 凭据与应用后端运行 Token、浏览器客户端分开管理。轮换是凭据操作，不是应用部署，也不保证零停机。

来源：[Token 操作与角色白名单](https://github.com/NexusFox88/docs/blob/main/resources/modules/credentials/application-tokens.ts)、[认证](https://github.com/NexusFox88/docs/blob/main/resources/modules/credentials/api-auth.ts)、[路由状态码和响应头](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 与独立测试身份验证了创建状态码和 no-store 响应头、元数据脱敏、轮换保留到期时间、旧 Token 拒绝、新 Token 可用、重复撤销、无效输入和跨租户拒绝。测试凭据随后已清理。检查使用 Fastify 注入，不是网络代理/TLS 测试或云任务验收。

## 按操作选择恢复方式

| 操作 | 成功响应 | 响应丢失后的处理 |
| - | - | - |
| 列表 | `200`，只有元数据 | 可以重新读取，但无法恢复明文 |
| 创建 | `201`，新 ID 与明文 Token | 用 owner 查询元数据，确认并撤销未使用项后再明确创建；label 不是唯一请求标识 |
| 轮换 | `200`，替代 ID/Token，保留原到期时间 | 旧凭据可能已经失效；检查元数据并对账替代凭据的交付，不要期望重试旧 ID 轮换能取回明文 |
| 撤销 | `200`，ID 与首次撤销时间 | 对同一 application ID 重复撤销保留时间戳，但不会回滚已经认证通过的工作 |

客户端应将创建的 `201` 识别为成功，不能因状态码意外而再次创建 Token。轮换与撤销仍返回 `200`。应按精确端点契约处理，不要给所有 Token 变更套用同一个状态码。

下一步：[身份操作指南](https://docs.hexagon.autos/zh-CN/operate/access-control.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.