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.
Get connection descriptors for the instance
Produces the connection descriptors shown by the Connect tab of the instance detail page: protocol
(SSH for Linux images, RDP for Windows), target host (floating IP preferred, else fixed IP),
port (22 or 3389), the OS-derived username (Administrator / ubuntu / admin / cloud-user), the
associated key-pair name, and a ready-to-paste client command (ssh -i … or mstsc /v:…).
No resource state is mutated; the call exists so the API can resolve credentials/host data
server-side and audit connection intents.
Validation: instance must exist and be visible → 404 NOT_FOUND; instance must be ACTIVE —
the UI warns "start it before connecting" and the backend rejects non-running instances →
409 CONFLICT; the instance must have at least one reachable IP (fixed or floating), otherwise
the host is returned as null and the command omitted.
Async & state: Synchronous (200) returning InstanceConnectionInfo; no instance state change.
No SSE frames are emitted for this action.
Errors: 401 UNAUTHENTICATED; 403 FORBIDDEN when the caller may not connect to resources in
this scope; 404 NOT_FOUND for an unknown instanceId; 409 CONFLICT when the instance is not in a
connectable (ACTIVE) state; 500 INTERNAL.
Idempotency/Concurrency: Effectively read-like but issued as a POST for auditability; this
operation does not use Idempotency-Key (it may be omitted and a sent one is ignored). Each
call recomputes the descriptor from the instance's current state, so repeated calls return the
same payload while the instance is unchanged. No If-Match applies since nothing is mutated.
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.
Connection descriptors for the instance (SSH/RDP host, port, username, command).
application/json- response
Connection descriptors rendered by the Connect tab. Contains no secret material — only host, port, username, the injected key-pair names and a ready-to-paste client command.
protocol*stringssh for Linux images, rdp for Windows images.
"ssh""rdp"host*|Floating IP preferred, else fixed IP; null when the instance has no reachable IP.
port*integer22 for ssh, 3389 for rdp.
username*stringOS-derived login user (Administrator, ubuntu, admin, or cloud-user). For a password-only Linux instance the literal placeholder <admin-user>: its admin account is the name chosen at create, which the platform does not store.
keyPairs*array<string>Names of the SSH key pairs injected at boot; any one of them authenticates. Empty for password/RDP-only setups. The rendered command uses the first.
[]command*|Ready-to-paste client command (ssh -i ... / mstsc /v:...); null when host is unknown.
curl -X POST "https://example.com/scopes/string/compute/instances/string/actions/connect"{ "protocol": "ssh", "host": "string", "port": 0, "username": "string", "keyPairs": [], "command": "string"}