Authorization

This part of the API handles authorization. The authorization is done based on JSON Web Tokens (JWT). The API can be used to get a JWT and retrieve information about it. The actuall access-role is included in the JWT and can be one of the following:

  • anon - anonymous, not authorized,
  • device - IoT Device
  • user - user of account(s)
  • admin - admin user of account(s)
  • sysadmin - admin with system wide rights
  • system - role of component doing system wide analytics
post

Get the JWS for a user. The token is unique for every request.

Token expiration:

User JWT token is valid for 24h and contains user access information. On access change, token should be refreshed, to use new privileges. Example situation that require token refresh:

  • User creates new account - to use new account, token must be refreshed
  • User has been invited to new account - to have access to this account, token should be refreshed
  • User account role has been updated, for instance admin privileges were granted - to use new level of access, token must be refreshed

The following access-roles are authorized for this path: anon, user, admin, sysadmin

get

Get info about the JWT token

The following access-roles are authorized for this path: anon, user, admin, sysadmin

get

Get user information about the owner of the JWT token

The following access-roles are authorized for this path: user, admin, sysadmin

User Management

Handles user creation, updating, deleting and password changes and retrieval

post

Add User Add new user. If not existing, email is added to the user DB and message is sent to the email owner to activate. If existing, User already esists error is given. In the open system, the access role is anon, i.e. everyone can request a tenant. It is recommended to protect the subscription by a challenge response test like Captcha to protect agains robot spamming. Closed or single tenant systems could protect by requesting an authenticated access role like admin.

The following access-roles are authorized for this path: anon

get

Get User information

The following access-roles are authorized for this path: user, admin, sysadmin

put

Update user attributes.

As an user, you can add attributes to your user data. Attributes can be any key/value pair.

The following access-roles are authorized for this path: user, admin, sysadmin

delete

Delete a User.

This action will result in deleting your user data, and also accounts if they do not have any other administrators. You will also no longer be able to use your old token.

The following access-roles are authorized for this path: user, admin, sysadmin

Change forgotten password.

In order to change password (for cases in which user do not remember the old one) you have to do following steps:

  • Invoke POST /users/forgot_password. After this step user will receive email with a url, which can be used to set a new password via IoT Dashboard. In email there will be user's token as a part of resetPassword url. Token is required for successful completion of next steps. Token is unique for user and action.
  • Invoke PUT /users/forgot_password, with token from email received by user after completion of point 1. In a request body you have to put new password and token.
post

Request change password

Methods generate and send email, which can be used to change password. User email has to be specified in request body.

The following access-roles are authorized for this path: anon, user, admin, device, sysadmin, system

put

Update password

Method set new password for the user. In request body you have put token received in a email (send after invoking POST /users/forgot_password) and the new password.

The following access-roles are authorized for this path: anon, user, admin, device, sysadmin, system

put

Change password

Methods set new password for a user (identified by email).

The following access-roles are authorized for this path: user, admin, sysadmin

post

Request user activation

Methods generate and send email, which can be used to activate user. User email has to be specified in request body and must be already in user DB, i.e. invited or added.

The following access-roles are authorized for this path: anon, user, admin, device, sysadmin, system

post

Activate User The activation has been requested earlier with the /request_user_activation path

The following access-roles are authorized for this path: anon, user, admin, device, sysadmin, system

Account Management

This API handles Accounts and User related operations

post

Create an Account

Important: After creating account, user Authorization token must be refreshed to access the new account data.

The following access-roles are authorized for this path: user, admin

get

Get Account information

The following access-roles are authorized for this path: user, admin, sysadmin

put

Update an Account

The following access-roles are authorized for this path: admin

delete

Delete an Account.

Deletes an Account and all its data.

The following access-roles are authorized for this path: admin

get

Get Account Activation Code

The Account Activation Code is the transient activation code that can be used to activate devices for the account. It expires after one hour.

The following access-roles are authorized for this path: user, admin, sysadmin

put

Renew Account Activation Code

Forces the renewal of the Account Activation Code.

The following access-roles are authorized for this path: admin

get

List all Users for Account

This call will retrieve a list of users assigned to an account.

The following access-roles are authorized for this path: user, admin, sysadmin

put

Change another user privileges to your account (you need to be an admin)

You can upgrade a standard user of your account (who currently has "user" privileges - default for invited users) to an admin. To do so, you have to be an admin of account for which you want to upgrade another user's access. {role} is supposed to be "user" or "admin".

Remember that user can be promoted from user to admin, but admin privileges cannot be revoked.

The following access-roles are authorized for this path: admin

Rule Management

This API is used to manage Rules. A Rule is an association between one or more device's components, a set of conditions for those components, and a number of actions that have to be triggered in case those conditions are met.

Supported rule action types

TypeTargetDescription
"mail"["test@example.com"]Array of recipients' email addresses
"http"["http://www.example.com"]Array of HTTP endpoints where request should be sent.They should expect and accept POST requests.
"actuation"["command"]Array of commands

To receive alerts as requests to HTTP endpoint, set "type" in actions section to "http" and "target" in the same section to desired endpoint. Additionally you can add custom HTTP headers to received alerts. To do this, add "http_headers" object to "actions" section if chosen action type is http. Example:

"actions": [
{
  "type": "http",
  "target": [
    "http://test.com"
  ],
  "http_headers":
    {
      "header1": "value1",
      "header2": "value2"
    }
}]
get

Get List of Rules

Get a list of all rules for the specified account.

The following access-roles are authorized for this path: user, admin, sysadmin

post

Create a Rule

The following access-roles are authorized for this path: user, admin

get

Get one Rule information

Get specific rule details for the account.

The following access-roles are authorized for this path: user, admin, sysadmin

put

Update a Rule

If rule doesn't exist it create a new one. Cannot be used for update of a draft rule.

The following access-roles are authorized for this path: admin

put

Update a Status of a Rule

Update the status of the rule. Cannot be used for changing the status of draft rule. Status value should be one of the following: ["Active", "Archived", "On-hold"]

The following access-roles are authorized for this path: admin

delete

Delete a Rule

Delete a rule with ID ruleId.

The following access-roles are authorized for this path: admin

put

Create a Rule as a Draft

Create a rule with a status - "Draft" for the specified account.

The following access-roles are authorized for this path: admin

delete

Delete a draft rule

Delete a specific draft rule for account

The following access-roles are authorized for this path: admin

post

Clone an existing Rule

The following access-roles are authorized for this path: user, admin

Alert Management

The Alert API is a REST Interface for handling alerts.

get

Get List of Alerts

Get a list of all alerts for the specified account.

The following access-roles are authorized for this path: user, admin, sysadmin

get

Get Alert information

Get specific alert details connected with the account.

The following access-roles are authorized for this path: user, admin, sysadmin

put

Reset Alert

Change alert status to - "Closed". Alert won't be active any more.

The following access-roles are authorized for this path: admin

put

Update Alert status

Change status of the Alert. Status should have one of the following values: ['New', 'Open', 'Closed']

The following access-roles are authorized for this path: admin

post

Add comments to the Alert

Add list of comments to the alert.

The following access-roles are authorized for this path: admin

Device Management

This section handles the device managent. E.g. add or register devices, remove devices, component management, search for devices. In many cases the {accountId} is clear implicitly since a Device is assigned to at most one account. Therefore, the respective accountId does not need to be given when access role is device. Instead a short version of the path, omiting accounts/{accountId}, can be used. For example, there is a short version of the path /v1/api/accounts/{accountId}/devices/{deviceId}, which is /v1/api/devices/{deviceId}.

A special case is the */activation method, which can be used by a new device to be added to an account, even though it does not (yet) belong to this account.

get

List Devices

If no query paramters are given, then it will retrieve a list of all devices for the specified account, with minimal data for each device. Otherwise, the query parameters will filter the desired result.

The following access-roles are authorized for this path: user, admin, device, system

post

Create a Device

Used to create a device. The access token in the header will be used to authenticate the account on the URL for which this operation is being performed.

Device ID should consist only A-Z, a-z, 0-9 and - characters Location is optional and only makes sense for stationary devices. It should be sent as [decimal latitude, decimal longitude, (optional) height in meters] using WGS84 Datum.

Device attributes should be sent as key:value pairs, where both key and value are string

Device attributes collection can not contain keys: deviceId, deviceName, gatewayId, tags, location, components.

The following access-roles are authorized for this path: user, admin, device, system

get

Get one Device

Get full detail for specific device for the specified account.

The following access-roles are authorized for this path: user, admin, device, system

put

Update One Device

Update a single device. The device ID (deviceId) cannot be updated as it is the key. If the device id does not exist, an error will be returned. The list of components represents the entire list of components for the device.

The following access-roles are authorized for this path: user, admin, device, system

delete

Delete one Device

Delete a specific device for this account. All data from all time series associated with the device will be deleted.

The following access-roles are authorized for this path: user, admin, device, system

put

Activate one Device

Activates a specific device for the specified account. If a device is activating itself, a short path, omitting accounts/{accountId} can be used because there is a unique mapping from activationCode to accountId

The following access-roles are authorized for this path: user, admin, device, system

post

Add a Component to a device

Add component to an specific device. A component represents either a time series or an actuator. The type must already existing in the Component Type catalog. You can see the entries in the catalog with a call in the Component section. Or, in the UI, go to the "Account" page and click the "Catalog" tab. Make sure you use in headers Device Token received during device activation process and not Access Token for your user. cid is a uuid created by the user. name and type are used according to the Component section.

The following access-roles are authorized for this path: user, admin, device, system

delete

Delete one Component

Delete a specific component for a specific device. All data will be unavailable.

The following access-roles are authorized for this path: user, admin, device, system

get

List all tags for Devices

Get a list of all tags from devices for the specified account.

The following access-roles are authorized for this path: user, admin, device, system

get

List all attributes of Devices

Get a list of all devices's attribute for the specified account.

The following access-roles are authorized for this path: user, admin, device, system

post

Advanced count of Devices

Counts devices's based on filters.

The following access-roles are authorized for this path: user, admin, device, system

Data API

post

Submit Data

Submit data from specific device. You can use REST API capabilities to submit data for specific device and it's component. Device and component have to be registered in the cloud before sending observations.

  • Device location (loc) should be sent as [decimal latitude, decimal longitude, height in meters] using WGS84 Datum

  • Attributes should be sent as key:value pairs, where both key and value sent as string

The following access-roles are authorized for this path: user, admin, device, system

post

Advanced Data Inquiry

Advanced Data Inquiry allows querying measurement data (values, location and attributes) for a single account using advanced filtering and sorting.

Attribute and Value filters

All filter keys and values are sent as strings (including numeric values).

gatewayIds, deviceIds and componentIds filter on the unique ID and can be used to pin-point a specific gateway/device/component.

valueFilter work on the "value" field of each measurement.

Attribute filters work on the device/component/measurement attributes. Each entry is an attribute name with a list of values to be matched.

For device and component, in addition to user-defined attributes, special metadata attributes can be used for filtering: groupPath, deviceName, Tags, componentName, componentType.

Different filters and different attributes within filters are evaluated with AND relation. Values in the value list are evaluated with OR relation:

  {
    "deviceIds" : ["ABC"],
    "componentIds" : ["123", "456"],
    "devCompAttributeFilter" : {"Tags" : ["Intel", "IOT"], "componentType" : ["temperature"]}
  }

  Means:

    (deviceId = "ABC") AND (componentId = "123" OR "456") 
    AND (Tags contains "Intel" OR "IOT") AND (componentType = "temperature")

The combination of gatewayIds, deviceIds, componentIds and devCompAttributeFilter determine the objects returned in the response. The other filters determine which records are returned for each object. Therefore, if a device satisfies the device filters but has no records that satisfy the value filter, it will return with an empty samples array. Conversely, if the filter combination is empty (e.g. componentID value that doesn't exist in the supplied deviceID), no objects will be returned. It is the client responsibility to ensure the filters sent are valid.

The device/component/gateway filters do not support "slowly changing dimensions": e.g. if the device list is filtered by deviceName and a device name changed from "My Device X" to "My Device Y" on April, his past measurements (January-March) will also be returned when requesting "My Device Y", although they were measured when the device name was different.

The following access-roles are authorized for this path: user, admin, device, system

Component Types Catalog

The Component Types Catalog API is a REST Service for maintaining a list of capabilities (with its associated data) that components connected to enableiot platform expose.

There are two main types of components:

  • Sensor
  • Actuator

    The catalog comes with default (built-in) component types which are available to all accounts (see the list here). These components will have the default field set to true. Each account can additionaly define custom component type which will be available only within that account.

    A Component-Type ID, which is account-level unique is a concatenation of its dimension and its version, seperated by a single period: e.g. "temperature.v1.0" or "humidity.v2.0".

    See section on Device-Management for an example of registering list of components associated to a Device.

get

List all Component Types for an Account

Get a list of all Component Types, with minimal data for each component if full paramter is omitted or false. If full=true the detailed data is retrieved.

The following access-roles are authorized for this path: user, admin, sysadmin

post

Create a new custom Component Type

When creating a brand new component, dimension and version attributes are used for determining if the component exists. If not, a new component is created which auto-generated id results the concatenation of dimension and version values.

The following access-roles are authorized for this path: user, admin

get

Get Component Type Details

Get a complete description of a component type specified by Id

The following access-roles are authorized for this path: user, admin, sysadmin

put

Update a Component Type

Updates a component type definition by creating a brand new component which definition is composed by the origin component data plus the requested changes having in mind that minor version info (version attribute) is incremented by 1.

The following access-roles are authorized for this path: admin

Control Device API

post

Send actuation command

Send actuation command to the device for specific component (actuator)

The following access-roles are authorized for this path: user, admin, device, system

post

Save complex command

Saves multiple simple commands as a complex one which can be later executed as one.

The following access-roles are authorized for this path: user, admin, device, system

get

Get list of actuations

Get list of actuation commands, which was send to the device. By default method returns list of actuations from last 24 hours. There is possibility to get list of actuations from specific period of time, by adding from and to parameters to the url request (see "from and to" paragraph below).

from and to

  • If the to key is omitted, data will be retrieved up to the current time.

  • If the from key is omitted, from will default to currentTime minus 24 hours. If from is positive it will represent the number of milliseconds since Jan-01-1970T00:00:00.000. However, if from is negative, it represents the number of seconds to add to to (because the number is negative, it will decrease to, moving backward in time.

  • There is no way to receive actuations, which were send to device before 24 hours. Only actuations from last 24 hours are stored in application database.

Here are some examples:

fromtomeaning
0missingReturn all data available
-86400missingreturn all data with timestamps in the last 24 hours (86,400 seconds)
14079792910001407980711000return all observations with timestamps between 2014-08-13T18:21:31.000 UTC and 2014-08-13T18:45:11.000 UTC

The following access-roles are authorized for this path: user, admin, device, system

Invitation Management API

get

Get List of Invitations

Get a list of users invited to the specific account.

The following access-roles are authorized for this path: user, admin, sysadmin

post

Create Invitation

Creation of invitation to the account for specific user (identified by email). Response documentation TBD.

The following access-roles are authorized for this path: admin

get

Get list of invitations sent to specific user

Get details about invitations send to specific user. User is identified by his email address.

The following access-roles are authorized for this path: user, admin, sysadmin

delete

Delete invitations

Delete invitations to an account for a specific user (identified by email).

The following access-roles are authorized for this path: admin

put

Accept Invitation

Accept pending invitation for the specific account.

The following access-roles are authorized for this path: admin