Skip to main content

User consent/Permissions Grant

Register / Deregister Shelly devices to Integrator service

Integrator URL​

Integrator uses specificity crafted url, adding the tag acquired earlier and a callback url (best practice to URL-encode).

https://my.shelly.cloud/integrator.html?itg=<TAG>&cb=<URL>

User Interaction​

User need to login with their existing Shelly account, then select from a list of devices, the ones to be shared with the Integrator and add additional access rights if needed.

Callback URL​

When a user Register (add) / Deregister (remove) a device the integrator will be notified on the provided callback URL, by a POST request with a JSON body:

{
    userId: number,
    deviceId: string,
    deviceType: string,
    deviceCode: string,
    action: "add|remove",
    host: "shelly-1-eu.shelly.cloud",
    name: ["Plug 1"]
}
  • Each Shelly device has a separate name for each channel it has.
  • Integrator must respond with 200 OK , otherwise the operation will discontinue.

Callback URL Security​

With every such request Shelly Cloud sends additional HTTP header SCL-Trust:<JWT_TOKEN>, where <JWT_TOKEN> is ES384 signed payload with content:

{
    exp: number, // UNIX_TIME_STAMP (TTL 2 minutes)
    itg: string, // INTEGRATOR_TAG
    did: string  // DEVICE_ID
}

the authenticity of this token can be verified with the following public key:

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE3Kx+6C/0ZbnelYUgucUo4/X4xt1NCmEL
coyLpgkuLHume4VLZnQjtXeYgzr2FUdsO/ip8SzssSu3CEU9ArvB+yGIlW7l1yLt
wHVs/2zXrL0riL++7jdoQCpTGanFVzpM
-----END PUBLIC KEY-----

The token undisputedly assures that the system generating the request have access to the private key only available to the Shelly Cloud instances. The token expires for just two minutes and only verifies single device id and single integrator making reply attacks practically meaningless added to the huge hurdle of having to eavesdrop and decrypt TLS traffic between Shelly Cloud and integrators cloud.