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

# Session 环境、授权与访问凭据

这些操作读取有效环境值、比较固定配置和当前连接授权、撤销单个 Session 的绑定授权，或签发限定范围的代理凭据。它们不修改 Session 固定配置，也不替换 Provider 凭据。

路径包含 `/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 列表；没有对应更新接口。

```sh theme={null}
umask 077
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" --output session-environment.json \
  "$HEXAGON_API_URL/v1/sessions/$HEXAGON_SESSION_ID/environment"
```

在私有目录执行，检查 curl 退出码后再读取响应；失败响应也可能写入文件。只需要环境名称和历史配置快照时，应使用 `/initialization`。

## 检查当前授权

`GET /v1/sessions/{id}/authorization` 返回 **200**、`{session_id,connections:[...]}`。它检查当前数据库中的连接、Secret 和撤销状态，不调用 Provider 或验证真实凭据有效性。

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

每项包含 id、name、kind、pinned\_version、current\_version、可空 secret:\{id,name}、raw\_secret\_in\_sandbox:false、可空 revoked\_at 和 state。Secret 元数据不包含值。状态按以下优先级判定：

1. Session 内已撤销 → revoked。
2. 连接已删除 → deleted。
3. 连接未启用/非 ready，或 managed Secret 未启用/已删除 → unavailable。
4. 非 Tool 连接当前版本与固定版本不同 → changed。
5. 其他 → ready。

Tool 版本差异不使用同样的 changed 分类。Ready 是本地授权观察，不是外部调用成功。环境与授权读取遇到不存在或其他租户 Session 返回 `404 session_not_found`。

## 撤销本 Session 的连接授权

`DELETE /v1/sessions/{id}/connections/{connection}` 要求 owner，返回 **200** 和更新后的 authorization 对象，不是 204。只有固定定义中的 Tool 或 HTTP 连接可以撤销，其他绑定或 kind 返回 `403 connection_not_bound`。

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

操作保存持久的 Session 内撤销记录，并撤销该 Session/连接的 access grants。重复不会新增重复撤销行。这不删除共享连接、不在 Provider 撤销账户，也不影响其他 Session；这里没有反向恢复接口。语句不在同一事务中，响应失败后应查询授权和 grants，必要时再次撤销同一绑定。未来代理授权本身也检查已记录的 Session 撤销。已派发外部操作不能收回。

## 列出访问凭据元数据

`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。

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

## 签发限定范围的代理访问

`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：

```json theme={null}
{"connection_id":"00000000-0000-4000-8000-000000000001"}
```

```sh theme={null}
umask 077
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @access-request.json --output session-access-grant.json \
  "$HEXAGON_API_URL/v1/sessions/$HEXAGON_SESSION_ID/access"
```

替换占位 UUID，私有保存响应并检查命令成功，不要将 owner Token 发给代理。凭据入口必须是有效 HTTPS origin。Session 必须 open；此操作对非 open Session 也返回 `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 整个连接绑定。

| 签发错误 | 状态与含义 |
| - | - |
| credential\_proxy\_not\_configured / credential\_proxy\_url\_invalid | 409，修复入口配置 |
| session\_not\_found | 404，不存在、其他租户或非 open |
| connection\_not\_bound | 403，不是模型或已绑定 HTTP 连接 |
| access\_denied | 403，Session 内连接已撤销 |
| connection\_not\_ready | 409，连接缺失、不可用或 kind 不符 |
| session\_connection\_changed | 409，当前版本与固定版本不同 |
| session\_access\_expired | 409，计算的授权截止时间无效 |

严格请求体不合法返回 `400 invalid_request`。后续代理传输使用独立策略和认证处理，见[受保护 HTTP API](https://docs.hexagon.autos/zh-CN/integrations/http-tools.md)。

## 撤销一个 grant

`DELETE /v1/access/{id}` 返回 **204**，无响应体。重复撤销存在的 grant 成功并更新撤销时间；未知或其他租户的 grant 返回 `404 access_not_found`。

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

这不会关闭 Session、撤销账户凭据或撤回已派发请求。Access grants 与[浏览器预览授权](https://docs.hexagon.autos/zh-CN/reference/artifacts-previews.md)不同。

## SDK 示例：分别检查、签发与撤销

按 SDK 安装说明在可信后端初始化 `client`；TypeScript 辅助函数使用已导入的 `Hexagon` 类型。以下函数彼此独立，定义函数不会发送请求。先验证应用用户与资源的对应关系，再传入已保存的 Session ID，以及目标连接或 grant ID。组合检查函数需要 owner 客户端，因为 Session 授权查询仅限 owner，虽然 grant 列表也允许应用 Token 查询。

```python theme={null}
def inspect_session_access(client, session_id):
    authorization = client.session_authorization(session_id)
    grants = client.list_access(session_id)['grants']
    return {'authorization': authorization, 'grants': grants}


def read_private_process_environment(client, session_id):
    return client.session_environment(session_id)


def issue_private_access(client, session_id, connection_id):
    return client.create_access(session_id, connection_id)


def revoke_one_access_grant(client, grant_id):
    client.revoke_access(grant_id)  # HTTP 204 -> None


def revoke_session_binding(client, session_id, connection_id):
    updated = client.revoke_session_connection(session_id, connection_id)
    return updated  # JSON authorization object, not None
```

```typescript theme={null}
async function inspectSessionAccess(client: Hexagon, sessionId: string) {
  const authorization = await client.sessionAuthorization(sessionId);
  const { grants } = await client.listAccess(sessionId);
  return { authorization, grants };
}

async function readPrivateProcessEnvironment(client: Hexagon, sessionId: string) {
  return await client.sessionEnvironment(sessionId);
}

async function issuePrivateAccess(client: Hexagon, sessionId: string, connectionId: string) {
  return await client.createAccess(sessionId, connectionId);
}

async function revokeOneAccessGrant(client: Hexagon, grantId: string) {
  await client.revokeAccess(grantId); // HTTP 204 -> undefined
}

async function revokeSessionBinding(client: Hexagon, sessionId: string, connectionId: string) {
  const updated = await client.revokeSessionConnection(sessionId, connectionId);
  return updated; // JSON authorization object, not undefined
}
```

检查函数执行两次独立读取，不是原子快照；它不会请求环境明文或 access token。返回的账户名称和资源 ID 仍可能是私有信息。列表保留已到期、已撤销的 grant，不能把数组长度当作可用 grant 数量。授权状态的本地 `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 审批流程。

| 实际意图 | 调用哪个函数、检查什么 | 仍需区分的边界 |
| - | - | - |
| 撤销一个泄露或闲置的委托 Token | 用 grant ID 调用单 grant 撤销函数；成功无 JSON | 其他 grant 和 Session 连接绑定不受这一操作撤销；也不撤回上游写入 |
| 禁止该 Session 使用已绑定 Tool/HTTP 连接 | 用 Session 和连接 ID 调用绑定撤销函数，检查返回 `connections` 的状态 | 没有撤销后的恢复端点；其他 Session、共享凭据、云计算资源各有独立生命周期 |
| 签发响应丢失 | 检查元数据，确认并撤销未使用 grant，再按需明确重新签发 | 列表无法找回 Token 明文；签发没有去重键 |
| 绑定撤销中途失败 | 读取授权和 grant 元数据，必要时重复同一撤销 | 多条语句不在一个事务内，失败响应不能证明每项 grant 更新都完成 |

这些函数向调用方传播错误，不自动重试。`session_connection_changed` 表示应调查固定版本差异，不允许据此修改既有 Session 的绑定。`connection_not_bound` 表示目标类型或绑定不满足条件，`access_denied` 可能来自 Session 撤销。签发时的 404 也可能表示 Session 已不再 open。行动前按上文的具体操作错误表判断。代理请求见[受保护 HTTP 指南](https://docs.hexagon.autos/zh-CN/integrations/http-tools.md)，broker 管理的调用见 [Tool 授权指南](https://docs.hexagon.autos/zh-CN/build/tool-authorization.md)。

本地语法或类型检查不证明真实环境读取、代理请求或撤销成功。仅定义示例函数不会读取任何秘密或签发凭据。

来源：[Session 配置](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/session-configuration.ts)、[访问签发与授权](https://github.com/NexusFox88/docs/blob/main/resources/modules/access/access.ts)、[HTTP 路由](https://github.com/NexusFox88/docs/blob/main/resources/apps/control-plane/server.ts)。本文经过源码审阅，本轮没有读取真实环境值或签发/撤销 grants。


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