# 获取沙箱终端短期令牌

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

取得当前沙箱终端 WebSocket 所需的短期令牌。它绑定当前身份、候选角色、工作区和沙箱，不是长期个人访问令牌。

```text
GET https://api.moi.matrixorigin.cn/v5/agent-sandboxes/{sandbox_id}/terminal
```

## 调用前准备

准备目标工作区的个人访问令牌与相应操作权限；环境、令牌、工作区和沙箱 ID 保持一致。[公共对象和结果确认](objects.md)说明资源身份、字段及状态。示例的资源值须替换为实际值。

## 请求

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl "https://api.moi.matrixorigin.cn/v5/agent-sandboxes/$SANDBOX_ID/terminal" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

:::::
:::::{tab-item} 参数说明

sandbox_id 为路径必填；无请求体。需要当前终端权限及已配置的终端服务。这个 GET 会签发敏感短期凭据，不能作为可随意缓存的普通详情请求。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "token": "<terminal-token>",
    "expires_at": "2026-11-11T08:01:00Z"
  }
}
```

:::::
:::::{tab-item} 字段说明

HTTP 200 的数据含义如下；示例值不是默认配置。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应说明。 |
| `data.token` | string | 签名终端令牌；不要放入共享日志或审阅材料。 |
| `data.expires_at` | string | 令牌过期时间，RFC 3339；当前签发有效期 60 秒。 |

:::::
::::::
:::::::

## 结果确认

在有效期内连接[终端 WebSocket](terminal-websocket.md)，使用该 token 而不是 PAT 作为连接查询参数。令牌只是连接时恢复身份，准入与后续会话仍重验当前权限。

## 错误处理

按 HTTP 状态及响应 code 判断；[公共错误与恢复](objects.md#错误与恢复)区分参数、权限、配额、提供商和结果未知。错误不证明尚未产生资源，也不能当成重试或清理已经完成。
