Get a short-lived sandbox terminal token

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.

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

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 describes resource identity, fields, and states. Replace example resource values with actual values.

Request

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"

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.

Successful response

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

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.

Confirm the result

Connect to the terminal WebSocket 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.

Error handling

Use HTTP status and response code. Common errors and recovery distinguishes parameters, permissions, quotas, providers, and unknown outcomes. An error does not prove no resource was created or that retries/cleanup have completed.

Last updated on