MS: Security

The ability to manage over a local network without a “security token” is blocked by default. This may be relevant, for example, when using local control in public places. The security token must be added to all change requests. The requirement for a security token in requests is determined by the parameter lanBlock 114 = 1 or in the thermostat menu by the item bLc = Lan. To disable this requirement, change the parameter lanBlock 114 to 0 or in the thermostat menu select oFF for the bLc item.

Note

The device additionally implements the ability to block operation through the Welrok cloud. This block is controlled by the parameter cloudBlock 115 = 1 or from the page http://dev_ip, where dev_ip is the device’s IP address on the local network.

Important

If both blocks are enabled simultaneously (parameters lanBlock 114 = 1 and cloudBlock 115 = 1; device menu item bLc = on), then the device is completely locked for remote control, even with authentication. Control is only possible via the buttons.

For authenticating the source when sending commands to the device, the TOTP protocol (RFC4226, RFC6238, Interval = 30 seconds, Digit = 9) is used, which generates a security token. To generate the security token, you need to know the key, which is a sequence of 16 bytes. It is generated by the cloud at the moment of first connection and every time the device is bound to an account. Remember that the key changes if the device is bound again to a Welrok personal account.

The key can only be obtained via the server API in 2 steps:

  1. Get an authorization token for the required account

  2. Get the list of devices with parameters bound to this account, where the 16-byte key will be specified.

OBTAINING AUTHORIZATION TOKEN

POST https://app.welrok.com/api/login/

{
   "email":"user@email.com",
   "password":"myPassword"
}
Parameters:

  • email - email of the registered Welrok application account

  • password - password for the Welrok application account

Response:

{
   "access_token":"9573e6a8e24b025fafbaf81dc2eccbc09b94d187",
   "user_name":"welrok",
   "is_timezone_chosen":true
}

access_token - the required authorization token

Authorization token request example:

POST /api/login/ HTTP/1.1
Host: app.welrok.com
Accept-Language: en
Content-Type: application/json

{"email":"demo@welrok.com","password":"demoaccount"}

OBTAINING LIST OF DEVICES WITH KEYS

GET https://app.welrok.com/api/device/ –header «Authorization: Token access_token»

Parameters

  • access_token - authorization token in the header

Response:

{
   "count": 4,
   "next": null,
   "previous": null,
   "results": [
               {
                  "id": 1,
                  "sn": "404CCAAAD4E8A89860609800000149",
                  "name": "ms",
                  "":""
                  "totp_key": "AAD4EXAJX4E8A8XT"
               }
              ]
}

The totp_key field in the parameters of each device contains the required 16-byte key for TOTP token generation.

Device list with keys request example:

GET /api/device/ HTTP/1.1
Host: app.welrok.com
Accept-Language: en
Content-Type: application/json
Authorization: Token 9573e6a8e24b025fafbaf81dc2eccbc09b94d187

SECURITY TOKEN GENERATION AND USAGE

After obtaining the key, using the TOTP protocol (RFC4226, RFC6238, Interval = 30 seconds, Digit = 9), you can generate a security token and use it in API change requests.

In such requests, two fields are added before the data fields:

time - time in seconds since 01/01/2000 00:00

auth - the calculated security token.

Then the request, for example, to turn on the device, change brightness to 1, and enable API change locking, would look like this:

{
   "sn":"404CCAAAD4E8A89860609800000149",
   "time":"634929122",
   "auth":"672201707",
   "par":[[125,7,"0"], [23,2,"1"], [114,7,"1"]]
}

Note

On 2-button devices, to do this you need to hold the right button from 36 to 39 seconds (3 seconds after resetting the settings). Indication: blinking red. 1. The LED turns off briefly once per second — the lock is enabled. 2. The LED turns on briefly once per second — the lock is disabled.

Note

The device has a page at http://dev_ip/index.html, where the function for connecting the device to the cloud API CLOUD BLOCK is available. If the CLOUD BLOCK item is enabled, the device’s connection to the cloud is active. If the CLOUD BLOCK item is disabled, the device has no connection to the cloud. When the connection to the cloud is disabled, no data is guaranteed to be transmitted to the cloud. However, this also means the device’s time is not synchronized with the cloud. The page is also accessible when the device operates in access point mode. To do this, switch the device to “AP” mode, connect to it, and go to: http://192.168.0.1/index.html

Note

The device has a page at http://dev_ip/index.html, where the CLOUD BLOCK function is available to block control of the device from the local network or remotely. If control blocking on the device is disabled (blc = off, parameter [114,7,”0”]) and CLOUD BLOCK is enabled, the device can be controlled only via the device buttons or from the local network. Remote control is blocked. Under these conditions, enabled CLOUD BLOCK corresponds to blocking control from the cloud (blc = cld) on the device, parameters [114,7,”0”] and [115,7,”1”]. If blocking of control from the local network is enabled on the device (blc = lan, parameter [114,7,”1”]) and CLOUD BLOCK is enabled, the device can be controlled only via the device buttons. Under these conditions, enabled CLOUD BLOCK corresponds to blocking of any network control (blc = cld) on the device, parameters [114,7,”1”] and [115,7,”1”]. The page is also available when the device operates in Access Point (AP) mode. To access it, switch the device to AP mode, connect to it, and open http://192.168.0.1/index.html