Get started using IoT Accelerator API following the steps described in this tutorial. This section provides the basic information that you will need to create your first project using IoTA APIs. The API documentation is available at this page. 

Initial setup

Here are the 3 main steps to follow:

1. Get an account: you can get an account subscribing to the service from your Connectivity Service Provider. You will then receive credentials to authenticate.

2. Authenticate: use the credentials you received in the API authentication step. The same credentials will be used for accessing the service portal and for API authentication.

3. Select and use the API: once you are authenticated, then you will be able to use the different methods listed in the API documentation page. Please refer to the table below for the authentication mechanisms used by the different API groups. The base URL for all API calls will be provided by your Service Provider when you subscribe to the service (URL example: https://iot-api.aeris.com).
All API requests are encrypted using the HTTPS protocol to grant secure data transfer.

API Authentication

There are different kind of APIs available in IoT Accelerator Service, which use slightly different authentication mechanism.
The following table describes the authentication mechanism used by the different API groups:

Authentication type: wss-security

The API uses the username token from the Web Services Security (WSS) specification.
The authentication must be put in the header of each SOAP message.
It contains a username and a password as shown in the following example:   

<soapenv:Header>
  <wsse:Security 
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
      wsse:mustUnderstand="1">
  <wsse:UsernameToken>
  <wsse:Username>{{My_UserID}}</wsse:Username>
  <wsse:Password>{{My_Password}}</wsse:Password> 
  </wsse:UsernameToken>
  </wsse:Security>
</soapenv:Header>

Authentication type: X-access-token

The API authentication is performed by passing a token in the X-Access-Token header in each request. The token can be acquired using the /login or /login-form endpoints. The login response contains the token expiration time in milliseconds. For prolonged interaction with the API, a new token can be reissued before the expiration of the current one using the /token-reissue endpoint.

Example of authentication:

curl -X POST "https://<baseURL>/dcpapi/rest/useradministration/login"
  -H "accept: application/vnd.dcp-v1+json"
  -H "Content-Type: application/json"
  -d "{ \"userId\":\"<USERNAME>\", \"password\":\"<PASSWORD>\"}"

Authentication type: Bearer

The API uses OAuth2 and OpenID Connect (OIDC) for authentication and authorization. The Authentication is performed by passing a token in the Authorization header in each request, preceded by the word Bearer and a space.

Example of API call

curl -i -X POST "http://<baseURL>/iot/api/ecm/enterprises" 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer <TOKEN_GOES_HERE>"
  -d "{\"parent_id\": \"3.77\",...

To fetch the token, submit the following:

curl -X POST "https://<baseURL>/iot/api/auth/token" 
  -H "accept: application/vnd.dcp-v1+json" 
  -H "Content-Type: application/x-www-form-urlencoded" 
  -d "grant_type=password&client_id=&username=&password="

REST APIs using BEARER TOKEN Authentication

The REST APIs which uses BEARER Token Authentication (in the table reported at the beginning of this same page) have a limitation in terms of maximum number of API calls per second. This limit is set per application. In order to know what is the limit in place for one of these API in terms of total capacity and residual capacity available, you should be looking at the header of every API response that you get from the system. Here is an example of the header information which an API response contains. The relevant attributes are evidenced in bold.

Response header
User-Agent: PostmanRuntime/7.29.2
Postman-Token: 3dbd698c-6b26-4902-ab47-xxxxxxxxx
Host: hostname.dotcom
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Response Headers 
Content-Type: application/json
Content-Length: 9260
Connection: keep-alive
X-RateLimit-Remaining-second: 9
X-RateLimit-Limit-second: 10
X-RateLimit-Remaining-minute: 57
X-RateLimit-Limit-minute: 60
X-Flow-ID: 8d7f9e1e-6c01-4e35-9af9-ea04e22c176e
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=16070400; includeSubDomains
X-Robots-Tag: none
Referrer-Policy: strict-origin
Permissions-Policy: geolocation=(), midi=(), sync-xhr=(self), microphone=(),
camera=(), magnetometer=(), gyroscope=(), fullscreen=(), payment=()

In this specific example, the API has a maximum limit of 10 request per second/60 requests per minute, and the available capacity is 9 requests per second/57 requests per minute.

It might happen that the header only contains the requests per seconds and not the requests per minute, and in some cases the header does not contain these information at all. There is an alignment process in place amongst all the APIs that will be finalized soon.

When the limit is reached, the API call is rejected and Error code 429 is provided in the body of the API response.

Example:

Response Body

{"message":"API rate limit exceeded"}

This means that the application is overloading the system with too many API calls and should decrease the frequency of API calls.

API endpoints permission are authorized by authorization server based on the account roles.
You can view available permissions for your account through permission library in Service Portal by navigating under the following menu: Administration > Users & roles > Permission library or Role administration > Actions > View permission library.
Make sure permission is available to your account before you start utilizing this API.
Soon you will see in this chapter a table which will summarize the permission required to access different API, so that you could use this information when asking your CSP Provider to activate a new API for your role.

API quota and throttling

REST APIs using BEARER TOKEN Authentication

The REST APIs which uses BEARER Token Authentication (in the table reported at the beginning of this same page) have a limitation in terms of maximum number of API calls per second. This limit is set per application. In order to know what is the limit in place for one of these API in terms of total capacity and residual capacity available, you should be looking at the header of every API response that you get from the system. Here is an example of the header information which an API response contains. The relevant attributes are evidenced in bold.

Response header

User-Agent: PostmanRuntime/7.29.2
Postman-Token: 3dbd698c-6b26-4902-ab47-xxxxxxxxx
Host: hostname.dotcom
Accept-Encoding: gzip, deflate
Connection: keep-alive

Content-Type: application/json
Content-Length: 9260
Connection: keep-alive
X-RateLimit-Remaining-second: 9
X-RateLimit-Limit-second: 10
X-RateLimit-Remaining-minute: 57
X-RateLimit-Limit-minute: 60
X-Flow-ID: 8d7f9e1e-6c01-4e35-9af9-ea04e22c176e
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=16070400; includeSubDomains
X-Robots-Tag: none
Referrer-Policy: strict-origin
Permissions-Policy: geolocation=(), midi=(), sync-xhr=(self), microphone=(),
camera=(), magnetometer=(), gyroscope=(), fullscreen=(), payment=()

In this specific example, the API has a maximum limit of 10 request per second/60 requests per minute, and the available capacity is 9 requests per second/57 requests per minute.

It might happen that the header only contains the requests per seconds and not the requests per minute, and in some cases the header does not contain these information at all. There is an alignment process in place amongst all the APIs that will be finalized soon.

When the limit is reached, the API call is rejected and Error code 429 is provided in the body of the API response.

Example:

Response Body

{"message":"API rate limit exceeded"}

This means that the application is overloading the system with too many API calls and should decrease the frequency of API calls.

API Permissions

API endpoints permission are authorized by authorization server based on the account roles.
You can view available permissions for your account through permission library in Service Portal by navigating under the following menu: Administration > Users & roles > Permission library or Role administration > Actions > View permission library.
Make sure permission is available to your account before you start utilizing this API.
Soon you will see in this chapter a table which will summarize the permission required to access different API, so that you could use this information when asking your CSP Provider to activate a new API for your role.