Skip to main content

User consent

Register / Deregister ↔ Integrator

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. Than select from a list of devices, the ones to integrate 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: number,
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: number // 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.

sequenceDiagram Integrator->>Shelly Integrator Portal page: Request by customer, tag and callback to Integrator provided Shelly Integrator Portal page->>Shelly cloud: Provide user selection to the cloud Shelly cloud->>Integrator: Provide user choice for device management