Skip to main content

Getting Started

Version: 2.2-beta

Introduction

We have developed connectivity API for integration, control and telemetry collection from our devices. This documentation is intended for third party integrators, that would like to control Shelly devices that are connected to our cloud systems. An integrator account is needed and for obtaining a license one you should contact us at support@allterco.com. Licenses for personal use are not provided. Our users have to log into their Shelly Cloud account to give consent for sharing a set of their devices. They can also revoke that consent later.

To acquire integrator account you should contact us as stated above. What you'll receive is tag & token unique identifiers.

Token

Use the provided integrator tag and 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>' \
--data-urlencode 'token=<INTEGRATOR_TOKEN>'

{
isok: true,
data: "<JWT>"
}

Web Socket Connection

Open web sockets connection and authenticate with the JWT.

wss://<HOST>:6113/shelly/wss/hk_sock?t=<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 main that more than one open socket may be needed.

Server location will be provided on device registration with the host parameter. Integrator must keep at-least one open connections to a server, where it has active users.

sequenceDiagram Integrator->>Shelly support: Contact support for license Shelly support->>Integrator: Provide tag and token Integrator->>Shelly cloud: Request short lived (24h) JWT Shelly cloud->>Integrator: JWT loop Secure WebSocket, provide acquired JWT Integrator->>Shelly cloud: control Shelly cloud->>Integrator: notifications end Integrator->>Shelly cloud: Device registration, deregistration