Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Establish (or re-establish) the web console connection for an instance
Establishes the UI-requested console connection for the selected instance in the active
tenant/subscription/project scope, as triggered by the "Connect" action button in
the instance console page. The API allocates (or refreshes) a console session and returns the full
session facts the console page renders: the wss:// endpoint with an embedded one-time console
token, protocol (RFB/noVNC), frame encoding, TLS cipher, resolution, keyboard layout, clipboard
policy, token expiry and session start time. Re-connecting after a disconnect resets the
framebuffer epoch so the boot stream replays from the beginning.
Validation: scopeId must be accessible to the caller (404 via ErrNotFound when unknown);
instanceId must identify an instance in that scope (404 NOT_FOUND otherwise); the instance's
current state must permit a console connection — an instance that is deleted or in a state that
cannot accept console sessions maps to 409 CONFLICT.
Async & state: Synchronous command returning 200 with the established ConsoleSession; the
session transitions connecting → connected server-side and the console badge state is surfaced
to other open consoles via resource.updated SSE frames of kind compute.consoleSession
(patch: state, startedAt, tokenExpiresAt). No durable instance state is changed.
Errors: 401 unauthenticated; 403 caller lacks an instance-console-capable role
(owner|admin|contributor) on the scope; 404 unknown scopeId or instanceId; 409 when the
instance state does not permit connect (e.g. stopped/terminating); 422 on malformed input;
500 on console-broker failure.
Idempotency/Concurrency: Send an Idempotency-Key; replaying the same key returns the same
session (same token and wsUrl) instead of allocating a second session. Concurrent connects to
the same instance from the same principal coalesce onto one session.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
instanceId*stringIdentifier of the compute instance whose console is being connected.
Idempotency-Key?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidConsole session established; session facts including the one-time console token (revealed only in this response).
application/json- response
Established web console session for an instance. The token is sensitive and is revealed only in the connect/connect-console response that creates the session.
wsUrl*stringWebSocket endpoint for the VNC stream, including the embedded one-time console token.
host*stringA label shown with the connection details (console.<region>), not an address: the console connects through wsUrl.
protocol*stringRemote framebuffer protocol descriptor (e.g. "RFB 003.008 (noVNC)").
encoding*stringFrame encoding negotiated for the session (e.g. "Tight + zlib (compression 6)").
cipher*stringTransport security descriptor (e.g. "TLS 1.3 · AES-256-GCM").
resolution*stringFramebuffer resolution (e.g. "1024×768").
latencyMs*integerMeasured round-trip latency to the console broker in milliseconds.
keyboard*stringKeyboard layout applied to the session (e.g. "en-US (auto-detected)").
clipboard*stringClipboard policy for the session (e.g. "Paste to guest only").
token*stringOne-time console token. Sensitive — returned only in the session-creating response, never in reads.
tokenExpiresAt*stringISO-8601 timestamp at which the console token expires.
startedAt*stringISO-8601 timestamp at which the session started.
osName*stringGuest operating system name (e.g. "Ubuntu 24.04.2 LTS").
kernel*stringGuest kernel version (e.g. "6.8.0-41-generic").
display*stringGuest display identifier (e.g. ":0 (ttyS0 mirrored)").
curl -X POST "https://example.com/scopes/string/compute/instances/string/console/actions/connect"{ "wsUrl": "string", "host": "string", "protocol": "string", "encoding": "string", "cipher": "string", "resolution": "string", "latencyMs": 0, "keyboard": "string", "clipboard": "string", "token": "string", "tokenExpiresAt": "string", "startedAt": "string", "osName": "string", "kernel": "string", "display": "string"}