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 |
|---|---|---|
|
string |
OK on success. |
|
string |
Response description. |
|
string |
Signed terminal token. Do not include it in shared logs or review materials. |
|
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.