Overview

The ClearBlade platform has the concept of “devices” – physical entities that interact with your system. Devices are similar to the “users” platform concept in that a device can authenticate itself with the system and perform various operations within the system. The ability to perform such operations is governed by ClearBlade’s Role-Based Access Control (RBAC) in the exact same way that it is applied to users.

Just like users, devices exist in a device table and by default, a device is allowed to only modify its entry in the table. Any device can have its own custom fields – fields that may only apply to that device, but could apply to any number of devices. Thus, the fields/columns in the device table are not homogeneous; certain fields are available for some devices, but not others. For example, you might want to define temperature sensor devices that have a “temperature” custom field. You could also define torque wrench devices that have a “current torque setting” field.

Device Authentication

While authentication for users is accomplished using passwords, devices are authenticated using pre-shared keys. These keys can either be manually set when creating devices, or they can be generated by the system for you.

To set up keys during device creation (CREATE /admin/devices/{systemKey}/{name}), three device attributes need to be set:

  1. allow_key_auth: Boolean. Set this to true
  2. active_key: String. This value will be the current active key and this must be shared with the “device” (or device surrogate) prior to device authentication. This is what is passed in when authenticating the device.
  3. keys: String. This is a comma-separated list of keys that can be cycled through using key rotation. Again, these keys are generated by the caller during the create operation.

If you want the system to generate keys, you use the CREATE /admin/devices/keys/{systemKey/{name}” endpoint. This will create a keyset, set the active_key, and set allow_key_auth to true. It will return the newly generated info.

To rotate keys, use UPDATE /admin/devices/keys/{systemKey}/{name}. All this does is set the new active_key. It is returned in the response.

To turn off key-based authentication, use DELETE /admin/devices/keys/{systemKey}/{name}.

To read the current active_key, and keys attributes, use GET /admin/devices/keys/{systemKey}/{name}.

Finally, to authenticate a device, use POST /api/v/2/devices/{systemKey}/auth endpoint. In the POST body you pass two key-value pairs {“deviceName”:“name-of-device”, “activeKey”: “value-for-active-key”}

Edge Synchronization

Like users, device state is automatically synchronized between ClearBlade and its Edges.

Enabled and Disabled Devices

Unlike users, devices can either be enabled or disabled. This roughly corresponds to commissioning/decommissioning devices in a real-world environment, and will be discussed in more detail later.