/v1,全部检查租户归属。前三项操作要求 owner;access grant 的列表、创建、撤销也允许应用 Token。示例使用可信后端 Token 和不带 /v1 的 HEXAGON_API_URL。环境响应及新签发 Token 必须私有保存。
读取有效环境
GET /v1/sessions/{id}/environment 返回 200、{env:{...},scope:"agent_process",mutable:false},并设置 Cache-Control:no-store。它解密保存的普通环境值,空环境为 {}。这不是脱敏初始化接口,也不是受保护 Provider/模型 Secret 列表;没有对应更新接口。
/initialization。
检查当前授权
GET /v1/sessions/{id}/authorization 返回 200、{session_id,connections:[...]}。它检查当前数据库中的连接、Secret 和撤销状态,不调用 Provider 或验证真实凭据有效性。
- Session 内已撤销 → revoked。
- 连接已删除 → deleted。
- 连接未启用/非 ready,或 managed Secret 未启用/已删除 → unavailable。
- 非 Tool 连接当前版本与固定版本不同 → changed。
- 其他 → ready。
404 session_not_found。
撤销本 Session 的连接授权
DELETE /v1/sessions/{id}/connections/{connection} 要求 owner,返回 200 和更新后的 authorization 对象,不是 204。只有固定定义中的 Tool 或 HTTP 连接可以撤销,其他绑定或 kind 返回 403 connection_not_bound。
列出访问凭据元数据
GET /v1/sessions/{id}/access 返回 200、{grants:[...]},按创建时间排列,无分页。每项包含 id、session_id、connection_id、可空 run_id、expires_at、revoked_at、created_at。过期或撤销项仍保留。列表不返回 token 或 base_url。Session 不存在或属于其他租户时返回 404。
签发限定范围的代理访问
POST /v1/sessions/{id}/access 接受严格 {connection_id:UUID},返回 201、{id,base_url,token,expires_at,implementation:"external_proxy"},设置 Cache-Control:no-store。Base URL 为配置的凭据入口 origin 加 /access/{grant-id}。Token 是委托凭据,不是原始 Provider Secret。
将真实连接 UUID 写入 access-request.json:
404 session_not_found。可签发对象为 Session 模型连接或绑定的受保护 HTTP 连接,不包括 Tool。连接必须启用、ready、未删除,且版本与固定版本一致;Session 内已撤销连接不能签发。
有效期从签发时起为 min(3600, Session timeout_seconds) 秒,后备值 600 秒;接口不接受用户 TTL 或 Run ID。公开签发的 run_id 为 null,worker 内部签发可绑定 Run,使用时额外检查 Run 活动状态。每次使用都会检查过期/撤销、Session open、连接版本/就绪、managed Secret 可用性及适用的 Run 状态。因此签发成功不保证稍后请求仍被授权。 内部绑定 Run 的授权在使用时只接受同 Session 下的 provisioning、running、waiting_authorization 或 waiting_approval;queued、cancelling 和终态不满足该检查。签发检查连接记录及固定版本,managed Secret 可用性在代理授权时检查,因此刚签发成功不能证明上游凭据当前可用。
接口不支持幂等键,重复会创建另一项,列表不能恢复明文。响应丢失后调查并撤销能明确识别的未用 grants,再主动签发新项。撤销单项 grant 不同于撤销 Session 整个连接绑定。
严格请求体不合法返回
400 invalid_request。后续代理传输使用独立策略和认证处理,见受保护 HTTP API。
撤销一个 grant
DELETE /v1/access/{id} 返回 204,无响应体。重复撤销存在的 grant 成功并更新撤销时间;未知或其他租户的 grant 返回 404 access_not_found。
SDK 示例:分别检查、签发与撤销
按 SDK 安装说明在可信后端初始化client;TypeScript 辅助函数使用已导入的 Hexagon 类型。以下函数彼此独立,定义函数不会发送请求。先验证应用用户与资源的对应关系,再传入已保存的 Session ID,以及目标连接或 grant ID。组合检查函数需要 owner 客户端,因为 Session 授权查询仅限 owner,虽然 grant 列表也允许应用 Token 查询。
ready 观察也不证明 Provider 访问成功。
只有明确需要不可变的 Agent 进程环境值时才调用环境函数。它返回 {env, scope, mutable},其中 env 是明文,不应进入常规诊断、UI 状态或日志。只需要名称时使用脱敏初始化端点。读取环境不会取出受保护 Provider 凭据,也不会修改运行中的进程。
签发函数返回 {id, base_url, token, expires_at, implementation}。私下持久化 grant ID 和到期时间,只将委托 Token 传给预期且已授权的使用方。访问返回的凭据代理 URL 时使用这个 Token,不使用 owner 或应用的控制平面 Token。签发仅适用于 Session 的模型连接或已绑定受保护 HTTP 连接,不能签发 Tool 绑定 grant,也不能传自定义 TTL 或 Run 参数。代理仍检查 method/path 策略,access grant 不会创建 Tool 审批流程。
这些函数向调用方传播错误,不自动重试。
session_connection_changed 表示应调查固定版本差异,不允许据此修改既有 Session 的绑定。connection_not_bound 表示目标类型或绑定不满足条件,access_denied 可能来自 Session 撤销。签发时的 404 也可能表示 Session 已不再 open。行动前按上文的具体操作错误表判断。代理请求见受保护 HTTP 指南,broker 管理的调用见 Tool 授权指南。
本地语法或类型检查不证明真实环境读取、代理请求或撤销成功。仅定义示例函数不会读取任何秘密或签发凭据。
来源:Session 配置、访问签发与授权、HTTP 路由。本文经过源码审阅,本轮没有读取真实环境值或签发/撤销 grants。