/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 或摘要。
创建应用 Token
POST /v1/tokens 接受严格 JSON 对象:
成功返回 201;包含 id、label、role:application、expires_at、created_at、token,响应头为 Cache-Control:no-store。生成值以 hx_app_ 开头,服务端存储 SHA-256 摘要。本次响应是取得明文值的机会,列表接口不能恢复明文。
请在新的私有目录执行。以下命令会创建凭据,并将完整响应保存到私有文件:
轮换应用 Token
POST /v1/tokens/{id}/rotate 无必需请求体,返回 200,字段与创建一致,并包含 Cache-Control:no-store。
404 application_token_not_found,不能找回丢失的替代明文。目标不存在、属于其他租户、为 owner、已过期或已撤销也返回此错误。响应丢失时用 owner 列表调查,撤销能明确识别但无法使用的替代项,再主动签发其他 Token;不能因为响应丢失就假定旧 Token 仍有效。撤销不会收回已经通过认证的请求,也不会取消其 Run。
撤销应用 Token
DELETE /v1/tokens/{id} 返回 200、{id,revoked_at},是 JSON 响应,不是 204。
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 总览生成;路由匹配仍须通过归属、参数和状态校验。 安装替代凭据后,使用它执行一个允许的读取,并确认旧凭据的新请求返回 401。Owner 凭据与应用后端运行 Token、浏览器客户端分开管理。轮换是凭据操作,不是应用部署,也不保证零停机。 来源:Token 操作与角色白名单、认证、路由状态码和响应头。凭据契约审阅使用当前处理器、真实 PostgreSQL 与独立测试身份验证了创建状态码和 no-store 响应头、元数据脱敏、轮换保留到期时间、旧 Token 拒绝、新 Token 可用、重复撤销、无效输入和跨租户拒绝。测试凭据随后已清理。检查使用 Fastify 注入,不是网络代理/TLS 测试或云任务验收。按操作选择恢复方式
客户端应将创建的
201 识别为成功,不能因状态码意外而再次创建 Token。轮换与撤销仍返回 200。应按精确端点契约处理,不要给所有 Token 变更套用同一个状态码。
下一步:身份操作指南、HTTP 总览。