curl -X POST "https://app.runtm.com/api/cloud/sessions/ses_abc123/ws-token" \
-H "Authorization: Bearer runtm_sk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{"capability": "terminal"}'
import requests
response = requests.post(
"https://app.runtm.com/api/cloud/sessions/ses_abc123/ws-token",
headers={
"Authorization": "Bearer runtm_sk_live_abc123...",
"Content-Type": "application/json",
},
json={"capability": "terminal"},
)
data = response.json()
ws_url = f"wss://app.runtm.com/api/cloud/sessions/ses_abc123/terminal?token={data['token']}"
const response = await fetch(
"https://app.runtm.com/api/cloud/sessions/ses_abc123/ws-token",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_sk_live_abc123...",
"Content-Type": "application/json",
},
body: JSON.stringify({ capability: "terminal" }),
}
);
const { token, expires_at } = await response.json();
const ws = new WebSocket(
`wss://app.runtm.com/api/cloud/sessions/ses_abc123/terminal?token=${token}`
);
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": "2026-05-09T21:05:00Z"
}
{
"detail": "Session not found"
}
{
"detail": "Session is not active"
}
WebSockets
Token Exchange
Exchange an API key for a short-lived WebSocket token
POST
/
api
/
sessions
/
{session_id}
/
ws-token
curl -X POST "https://app.runtm.com/api/cloud/sessions/ses_abc123/ws-token" \
-H "Authorization: Bearer runtm_sk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{"capability": "terminal"}'
import requests
response = requests.post(
"https://app.runtm.com/api/cloud/sessions/ses_abc123/ws-token",
headers={
"Authorization": "Bearer runtm_sk_live_abc123...",
"Content-Type": "application/json",
},
json={"capability": "terminal"},
)
data = response.json()
ws_url = f"wss://app.runtm.com/api/cloud/sessions/ses_abc123/terminal?token={data['token']}"
const response = await fetch(
"https://app.runtm.com/api/cloud/sessions/ses_abc123/ws-token",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_sk_live_abc123...",
"Content-Type": "application/json",
},
body: JSON.stringify({ capability: "terminal" }),
}
);
const { token, expires_at } = await response.json();
const ws = new WebSocket(
`wss://app.runtm.com/api/cloud/sessions/ses_abc123/terminal?token=${token}`
);
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": "2026-05-09T21:05:00Z"
}
{
"detail": "Session not found"
}
{
"detail": "Session is not active"
}
Creates a short-lived JWT that authenticates a WebSocket connection. The token is scoped to a single session and capability. Tokens expire after 5 minutes - request a new one if the connection drops.
Required scope: depends on the requested capability:
| Capability | Required scope |
|---|---|
terminal | sessions:terminal |
prompt | sessions:prompt |
collaborate | sessions:read |
Path Parameters
string
required
The session ID to connect to (e.g.
ses_abc123).Headers
string
required
Bearer token. Example:
Bearer runtm_sk_live_abc123...string
Scope to an organization.
Body
string
required
The WebSocket channel to authenticate for:
terminal, prompt, or collaborate.Response
string
Short-lived JWT for WebSocket authentication. Pass as the
token query parameter when connecting.string
ISO 8601 timestamp when the token expires.
curl -X POST "https://app.runtm.com/api/cloud/sessions/ses_abc123/ws-token" \
-H "Authorization: Bearer runtm_sk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{"capability": "terminal"}'
import requests
response = requests.post(
"https://app.runtm.com/api/cloud/sessions/ses_abc123/ws-token",
headers={
"Authorization": "Bearer runtm_sk_live_abc123...",
"Content-Type": "application/json",
},
json={"capability": "terminal"},
)
data = response.json()
ws_url = f"wss://app.runtm.com/api/cloud/sessions/ses_abc123/terminal?token={data['token']}"
const response = await fetch(
"https://app.runtm.com/api/cloud/sessions/ses_abc123/ws-token",
{
method: "POST",
headers: {
"Authorization": "Bearer runtm_sk_live_abc123...",
"Content-Type": "application/json",
},
body: JSON.stringify({ capability: "terminal" }),
}
);
const { token, expires_at } = await response.json();
const ws = new WebSocket(
`wss://app.runtm.com/api/cloud/sessions/ses_abc123/terminal?token=${token}`
);
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": "2026-05-09T21:05:00Z"
}
{
"detail": "Session not found"
}
{
"detail": "Session is not active"
}