Mint a WebSocket handshake ticket

POST

/api/v1/realtime/ticket

const url = 'http://localhost:3000/api/v1/realtime/ticket';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:3000/api/v1/realtime/ticket \
  --header 'Authorization: Bearer <token>'

Returns a short-lived, single-use ticket bound to the caller and the resolved organization. Redeem it once as wss://<host>/ws?ticket=<ticket>. A ticket is consumed on redemption, so each connection attempt — including every reconnect — requires a freshly minted ticket.

Authorizations

bearer

Parameters

Header Parameters

x-organization-id

string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Responses

201

Ticket minted

application/json

object

ticket

required

Opaque single-use handshake ticket. Pass it as the ticket query parameter on the WebSocket upgrade. It carries no claims and is consumed on first redemption.

string

expiresIn

required

Ticket lifetime in seconds. Redeem it immediately; it is not a session token.

number

Example

{
  "ticket": "a3f1c0de9b2447e8a1d6f05c7b3e9821a3f1c0de9b2447e8a1d6f05c7b3e9821",
  "expiresIn": 60
}

401

Unauthorized — invalid or missing authentication

403

Forbidden — no accessible organization context