Socket

Live updates travel over a single websocket per client. Authentication is a two-step handshake, because a websocket upgrade cannot carry DPoP headers:

1. GET /api/v1/socket/ticket (authenticated, with DPoP) mints a single-use ticket, valid for 30 seconds.
2. Connect to wss://<host>/api/v1/socket?ticket=<ticket> — no auth header. Every connect, including every reconnect, needs a fresh ticket.

There is no subscribe message: once connected, the client receives every event of its tenant that the account may read. The access snapshot taken when the ticket was issued decides what that is; reconnect to pick up access changes.

Wire format

Each event is one JSON text frame — the backend action verbatim:

{ "type": "OBJECT_UPDATED", "resourceIdentifier": "crn#tenant:….device:….service:…", "payload": { } }

Payload shapes are documented per module in the Events section of each module page — for a typical application chiefly OBJECT_UPDATED (property values) and META_STATUS_CHANGE (connectivity).

Note: propId inside flake payloads is a decimal number (2048), while REST uses hex strings (0x0800).

Heartbeat

Send {"type":"HEALTHCHECK_PING"}; the server answers {"type":"HEALTHCHECK_PONG"}. A connection that stops answering is dead even while the socket still looks open — terminate it and reconnect with a fresh ticket.

A worked client (connect, heartbeat, backoff reconnect) is part of the guide chapter WebSocket & Events.

GET	Issue a websocket ticket/api/v1/socket/ticket

Issue a websocket ticket

Mints a single-use ticket, valid for 30 seconds, that authenticates the websocket upgrade at /api/v1/socket?ticket=… — the upgrade itself cannot carry DPoP headers.

GET/api/v1/socket/ticket

Response

Name	Description
ticketstring	Single-use websocket ticket; present it as the ticket query parameter on the upgrade within 30 seconds.

Errors

Status	Description	Body
401	No valid access token was presented, or the DPoP proof accompanying it was missing, expired or bound to a different key.	error: string
500	The request failed for a reason that is not the caller's to fix. Safe to retry.	error: string, message: string, statusCode: 50

---