<span id="获取沙箱终端短期令牌"></span>

# Get a short-lived sandbox terminal token

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

Obtain a short-lived token for the current sandbox terminal WebSocket. It binds the current identity, candidate role, workspace, and sandbox, and is not a long-lived personal access token.

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

<span id="调用前准备"></span>

## Before you call this API

Prepare a personal access token and operation permissions for the target workspace. Keep environment, token, workspace, and sandbox ID consistent. [Common objects and result confirmation](objects.md) describes resource identity, fields, and states. Replace example resource values with actual values.

<span id="请求"></span>

## Request

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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} Parameters

sandbox_id is required in the path; there is no body. Current terminal permission and a configured terminal service are required. This GET issues sensitive short-lived credentials; do not treat it as an ordinary cacheable detail read.

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

HTTP 200 data has the following meaning; example values are not defaults.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response description. |
| `data.token` | string | Signed terminal token. Do not include it in shared logs or review materials. |
| `data.expires_at` | string | Token expiration in RFC 3339 format. Current validity is 60 seconds. |

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

<span id="结果确认"></span>

## Confirm the result

Connect to the [terminal WebSocket](terminal-websocket.md) before expiration, using this token rather than a PAT as the connection query parameter. The token restores identity at connection time; admission and subsequent sessions still revalidate current permissions.

<span id="错误处理"></span>

## Error handling

Use HTTP status and response code. [Common errors and recovery](objects.md#错误与恢复) distinguishes parameters, permissions, quotas, providers, and unknown outcomes. An error does not prove no resource was created or that retries/cleanup have completed.
