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": "az",
                  "":""
                  "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, hold the left button until the reg menu appears. Press the left button to navigate to the bLc menu item. Press the right button to select the oFF item.