Record where to wake this device
Presence answers which endpoints are alive. This answers what presence cannot: how to reach one that is not running. A killed app stops heartbeating and correctly leaves the extension fan-out — there is no socket to receive a call — so reaching it needs an out-of-band push, and a push needs an address. Send a PushKit VoIP token on iOS or an FCM registration token on Android. Call this on every launch: these tokens rotate silently on reinstall, restore and app-data clear, and a client that registers once will stop ringing with nothing to indicate why. The token is stored as given, not hashed — it is an address handed to Apple or Google verbatim, not a secret we verify. It is never returned by any endpoint.
Authorization
deviceAuth A per-device secret issued by POST /v1/devices/enroll, presented as
Authorization: Device <secret>.
A distinct scheme rather than another bearer flavour: the bearer namespace already carries workspace API keys and session JWTs, and a device secret authorises far less than either — it can mint a WebRTC token for its own identity and report presence, and nothing else.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
curl -X PUT "https://example.com/v1/devices/push-token" \ -H "Content-Type: application/json" \ -d '{ "push_token": "string" }'Mint a WebRTC token for this device POST
Authenticated with the device secret. The PBX identity is taken from the device record — a caller-supplied name is ignored, so a device cannot mint a token that rings as a colleague. Tokens are short-lived (about an hour); refresh on launch and on returning to the foreground.
Forget where to wake this device DELETE
Call on sign-out, or when notification permission is withdrawn. A token left behind that can no longer ring is not harmless: every wake attempt against it is silent waste. Revoking a device clears its token too.