Server terminal

The Terminal API opens a live shell (a PTY) on one of your SSH-managed servers and streams it to the browser over a WebSocket — the dashboard's server Terminal tab, backed by xterm.js. Because a browser can't set an Authorization header on a WebSocket(), auth is split into two steps: a normal HTTP call mints a short-lived, single-use ticket, and the WebSocket upgrade presents that ticket inside its Sec-WebSocket-Protocol header.

Mint a ticket

Opening a PTY is administrative, so the caller must hold server:admin on the target server. The endpoint also confirms the server exists in your organization (returning the same 404 the WebSocket would) before issuing the token.

POST /api/terminal/ticket

curl -X POST "$SYNQ_URL/api/terminal/ticket" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123"}'

The response carries the one-shot token and its lifetime:

{ "success": true, "token": "<opaque-single-use-token>", "expiresIn": 30 }

The token is consumed the first time it's presented on an upgrade — it cannot be replayed. Mint a fresh ticket per connection attempt.

Open the WebSocket

GET /api/terminal/ws/:serverId

Connect to the wss:// form of this path and pass the ticket as a WebSocket subprotocol. Browsers send subprotocols in the Sec-WebSocket-Protocol header; the value must be the prefix synq.terminal.v1+ followed by the token from /ticket:

const { token } = await fetch("/api/terminal/ticket", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ serverId }),
}).then((r) => r.json());

const ws = new WebSocket(`wss://your-host/api/terminal/ws/${serverId}`, [
  `synq.terminal.v1+${token}`,
]);

The upgrade enforces, in order: the request Origin must be a trusted origin; the ticket must be valid (or a same-origin session cookie present); the ticket's serverId must match the path; the caller must hold server:admin; the server must exist in the org; and the per-user concurrent-session cap must not be exceeded. Any failure opens the socket only to send an error control frame and close with a 4xxx code.

Resuming a parked session

When the socket drops without an explicit close, the shell is parked (kept alive) so the client can reattach. To resume, present a second subprotocol alongside the ticket: synq.terminal.resume+<resumeToken>, where resumeToken came from the previous ready frame. A resume reuses the existing PTY and audit row and does not count against the session cap.

Wire protocol

Once open, framing is:

• Binary frames, both directions — raw PTY bytes. Client → server bytes are written to the shell's stdin; server → client bytes are shell stdout/stderr.
• Text frames — JSON control messages.

Client → server control messages:

Server → client control messages:

Errors

error frames carry a machine-readable code: ssh_auth, ssh_connect, server_not_found, max_sessions, idle_timeout, session_cap, resume_failed, or server_error. The accompanying close code is in the application 4xxx range.

Operations