Integrate Device Data into Your SaaS

Use Case

Use this pattern when WLTE device capability is one part of your own product (a multi-tenant SaaS, an internal operations system, or similar). Your end users interact with your product and your own account system — they never touch WLTE credentials directly.

• One WLTE account and one API Client back your entire deployment, not one credential per end customer.
• Devices under a WLTE account are flat; there is no tenant concept. Which devices belong to which customer is a mapping you own and maintain.
• Live events need to flow continuously into your own data pipeline (database, message queue, your own WebSocket or webhook), rather than having every end-customer page hold its own connection to WLTE.

Never hand clientId, clientSecret, or an access token to an end customer. Do not assume devices under one account are isolated by tenant — they are not.

Recommended Architecture

Only your backend holds WLTE credentials. Maintain a deviceId → tenantId mapping, serve every tenant from one WebSocket connection, and fan out downstream through your own system.

Step-by-Step Implementation

1. Design and maintain a deviceId → tenantId (or your own customer/site identifier) mapping. WLTE accounts do not distinguish tenants — this table is the core data structure of the whole integration.
2. Obtain an access token from your single, server-held API Client: device:read for read-only use, plus device:control or device:config if you issue commands.
3. Call List Devices and List Device Type Definitions to build the initial state baseline, then split it into per-tenant views using your mapping table.
4. Create a one-time WebSocket ticket and establish a single connection — not one per tenant — to receive connection events, state-change events, and power events.
5. On each event, look up the tenant by deviceId first, then write to your own store or queue so your API/WebSocket/webhook can push it to that tenant's clients.
6. When an end customer issues a control request, authorize it against your own permission system first (your product's per-tenant permissions, not a WLTE scope), then have your backend proxy the request to WLTE with an idempotency key.
7. Persist command results and events yourself wherever you need long-term retention or a billing record — WLTE does not replay event history, and command records are retained only briefly.

Key Interfaces and Events

Purpose	Reference
Build the state baseline	List Devices
Capability-driven multi-tenant views	List Device Type Definitions
Add a device to the account	Add Device to Account
WebSocket authentication	Create WebSocket Ticket
Connectivity changes	Device Connection Events
Peripheral-state changes	Device State Changed Event
Power lost and restored notifications	Device Power Events
Proxy a control command	Create Relay Command
Poll a command result	Get Command Result

Failure and Recovery

• Rate limits are counted per API Client. Multiple tenants sharing one account share one rate-limit budget — a single tenant's high request rate can exhaust the whole account's quota, so throttle and queue at your own layer instead of passing end-customer request rates straight through to WLTE.
• On upstream WebSocket loss, reconnect the one server-side connection rather than reconnecting per tenant; mark downstream data as potentially stale while reconnecting.
• Events missed while disconnected are not replayed. Rebuild the state baseline through REST after reconnecting, then resume event-driven updates.
• Command records and idempotency keys are retained on the WLTE side for about 48 hours only. Persist command results and final status yourself if you need a longer audit or billing window.
• On 429 RATE_LIMITED, wait for Retry-After. Do not implement a separate independent retry loop per tenant in your own service.

Production Considerations

• End customers must never see or obtain WLTE's clientId, clientSecret, or an access token under any circumstance — every WLTE call must go through your backend.
• WLTE's four scopes (device:read/device:control/device:config/device:manage) are coarse, account-level permissions. They do not substitute for your own fine-grained, per-customer permission model — the two are separate authorization layers.
• Treat the deviceId → tenantId mapping as the most important table in your system; keep it in sync whenever devices are added or removed from the account, or customers add or remove sites, to avoid data crossing into the wrong tenant.
• Plan your rate-limit budget ahead of time: tenant count grows your request volume linearly, but the account's rate limit does not grow with it.
• See Authorization Scopes for available scope combinations and Rate Limits and Retries for the rate-limit dimensions.

Next Steps

• Build a Device Monitoring Dashboard
• REST API vs WebSocket
• Authorization Scopes
• Rate Limits and Retries