We have developed connectivity Cloud-to-Cloud API for integration, control and telemetry collection from our devices. This documentation is intended for third party integrators, that would like to monitor and control Shelly devices that are connected to our cloud systems. It allows centralized streaming of status data from many shelly accounts to a single point for data ingest. Basic control over the devices is also possible. An integrator account holding integrator's communications endpoints must be created. For creation of the integrator's account and for obtaining a license you should contact us at firstname.lastname@example.org or fill this form Licenses for personal use are not provided.
Device owners willing to use integrator's services have to log into their Shelly Cloud account and give consent for sharing a set of their devices with any intergrator. They can also revoke that consent later.
If your use case is more shelly account centric consider using Real Time Events API where similar functionality is offered but authentication is OAuth based via the Shelly account owner's credentials
If you want to be independent from the Shelly Cloud and you use Gen 2 devices, we advise you to check - Shelly Fleet Management
Expected architecture on the integrator side
Acquire integrator account
Device Permission Grant
The Users grant Integrator the right to monitor their devices on
The integrator should have the
<URL> provided with
cb arg always accessible so the Integrator backend can learn about new
devices that need to be monitored and new shelly cloud server that need to be connected. See User consent/Permissions Grant
Request access token
Use the provided integrator
token to acquire JWT (Access Token valid
24h) used for issuing WSS connection. Valid JWT is required when issuing a new
connection. The connection can persist indefinitely.
curl -X POST 'https://api.shelly.cloud/integrator/get_access_token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'itg=<INTEGRATOR_TAG>' \
Web Socket Connection
Open web sockets connection and authenticate with the JWT.
There are multiple Shelly cloud servers, each user and his/hers devices always connect to the same server. The WSS connection to a Shelly server will receive the data for all devices with enabled integration connected to that server. Keep in mind that more than one open socket may be needed, one to each server, where Integrator have customers on. We only allow one active connection per server.
Proper server name for WSS connection will be provided on device permission grant with the
parameter. Integrator must keep at-least one open connections to a server, where
it has active users.
N.B. This API delivers data to single location in Integrator infrastructure. If the Integrator need to use this information in multiple servers/datacenters, it's up to the Integrator to distribute the data inside it's infrastructure