Backend HTTP & MQTT Reference
Summary of the backend-facing contracts a partner integration should expect.
Authentication
HTTP headers
X-App-ID: <appId>
X-User-ID: <externalUserId>
Authorization: Bearer <userHash>
MQTT credentials (no Bearer prefix)
username: sdk:<appId>:<externalUserId>
password: <userHash>
The partner backend stores the app secret and generates userHash. The SDK does not hold the app secret or call the partner signing flow.
Identity endpoints
GET /v1/sdk/me
Used by the SDK to enrich the signed session with canonical backend identity.
SOS endpoints
POST /v1/sdk/sos/cancel
Transactional SOS cancel.
No business meaning should be inferred from the HTTP response alone. Final SOS lifecycle state comes from the operational runtime.
GET /v1/sdk/sos
Used for SOS rehydration on startup and after identity refresh.
Device registry
/v1/sdk/devices
Backend device registry surface.
Response fields:
| Field | Description |
|---|---|
id | Backend device record ID |
hardwareId | Canonical device hardware identifier |
firmwareVersion | Device firmware version |
hardwareModel | Device hardware model |
pairedAt | Pairing timestamp |
createdAt | Record creation timestamp |
updatedAt | Last update timestamp |
Contacts
Contacts are aligned 1:1 with the backend contract.
Fields:
| Field | Description |
|---|---|
id | Contact record ID |
name | Contact name |
phone | Contact phone number |
email | Contact email |
priority | Priority order |
createdAt | Record creation timestamp |
updatedAt | Last update timestamp |
Operational transport
The SDK uses operational transport (MQTT) for SOS and telemetry flows. Topic naming and transport details must stay aligned with the backend contract — do not hardcode them in the host app.
The configured broker URI may use ssl://, tls://, tcp://, ws://, or wss:// depending on environment and runtime transport client.