API: quick start guide

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://m2m.dcp.ericsson.net).
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:

API Technology Auth Type API token release

Service Portal

SOAP

wss-security

N.A.

User Administration

REST

X-access-token

POST/login

Consumer Connectivity

REST

X-access-token

POST/login

Subscription Management

REST

X-access-token

POST/login

Device Localization

REST

X-access-token

POST/login

Shared bundle

REST

Bearer

POST /token

Enterprise Management (CSP only)

REST

Bearer

POST /token

eUICC Setup (CSP & Advanced Resellers only)

REST

Bearer

POST /token

Device Reconnect

REST

Bearer

POST /token

Subscription Change History

REST

Bearer

POST /token

Subscription management - addictional functions

REST

Bearer

POST /token

Search Subscription Details

REST

Bearer

POST /token

Ticketing service for incident management

REST

Bearer

POST /token

SMS messaging

REST

HTTP Basic Auth

N.A.

Enterprise Provisioning for Marketplace HUB (CSP only)

REST

Bearer

POST /auth/login

Custom fields

REST

Bearer

POST /token

Subscription location

REST

Bearer

POST /token

Subscription signalling usages

REST

Bearer

POST /token

Subscription signalling events

REST

Bearer

POST /token

Devices: eUICC inventory view

REST

Bearer

POST /token

 

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>undefined</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.

API Description

POST /login 

Sign in and authenticate the user

POST /login-form   

Sign in and authenticate the user

POST /token-reissue

Returns a new token



Example of authentication:

curl -X POST "https://m2m.dcp.ericsson.net/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="

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, 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 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.