Assets API

All requests to the web API require authentication. This is achieved by sending a valid Bearer access token in the request headers. Request tokens are obtained using OAuth2.0.

Requests to the API can be done authenticated as your client or authenticated as a specific user. In both cases, you will first need to create a client and request a token.

When performing actions authenticated as a client, they will belong to service-account-CLIENTID.

Make sure you are calling our services over HTTPS when retrieving an access token.

The base object in the Assets universe is the asset. An asset represents a piece of equipment in a plant, ranging from the plant itself to the smallest sensor inside. An asset has a name and a description, along with some other properties.

There are two main types: ASSET and ATTRIBUTE: while an ASSET would be defined as a component of the installation, an ATTRIBUTE would be defined as a property on that asset. Those properties are usually pointers to certain tags containing timeseries data.

To define the asset structure of a (part of a) plant, we need a way to define the parent-child relationships between the different assets. This is done in the form of long paths. An asset has a list of (long) paths over which it can be reached. The long path is built with the identifiers of the parent and ancestor assets of the asset, all the way up to the root of the tree.

Next to the long paths array, a simpler and short paths array is present as well. The shorter paths refer to the same parents and ancestors, but simply with shorter identifiers.

An asset can have multiple paths because it can occur in more than one location in an asset tree.

Paths and long paths can be used interchangeable in the API. Within the same request using paths, all provided paths need to either be long paths or short paths.

Apart from the ASSET and ATTRIBUTE type, a special type called ASSET_ROOT is available. For every asset tree, one asset of this type is generated. It has the same name as the source in which it is defined, and is the highest ancestor of every asset in the tree.

To restrict access to certain assets, access rules can be assigned to assets and attributes. For simplicity, both assets and attributes will be called assets.

There are three different permissions defined:

For clarity, the prefix ASSET_ will be omitted in the remainder of this documentation, unless needed or specified otherwise.

The above permissions can be granted to subjects, the subject types:

In the current release, the subject types GUEST and GROUP cannot be used yet.

When defining an access rule on an asset, a combination of a subject and a set of permissions needs to be provided. When using the USER subject type, additionally a user id needs to be provided.