M2M API Overview

The M2M API provides an automated accesss to use M2M Cockpit for the management of M2M SIM cards. Using the M2M REST API, a user can:

• retrieve a SIM profile
• request a SIM profile activation
• request a SIM profile deactivation
• request a SIM profile reactivation
• request a SIM profile termination

Important prerequisite

You can start using the M2M API only if you have a valid and active M2M Cockpit subscription. For new customers looking to acquire M2M SIM cards and/or get an account on M2M Cockpit, you may do that here.# Getting started

Introduction

To work with the M2M API, you will need:

• the MSISDN (Mobile Station Integrated Services Digital Network) of the SIM card(s) you want to perform an operation on
• the API key coming from your M2M Cockpit account
• the OAUTH 2 access token from your API Solutions account

Read SIM card details

Retrieving information about a specific SIM card is performed with the following API call:

Sample request

curl -L -X GET 'https://api.enco.io/m2m/1.0.0/simcards?msisdn={your_msisdn}' \
-H 'x-api-key: {your M2M cockpit API key}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {your API Solutions OAUTH2 token}'

The API will return currently known information about this specific SIM card, including associated plans (data, SMS and voice) and related feature codes and service areas.

Sample answer

[
  {
    "AccessPoints": [
      {
        "Code": "string",
        "Properties": {
          "StaticIP": "string",
          "UserName": "string",
          "CustomName": "string"
        }
      }
    ],
    "CustomFields": {
      "Custom Field 1": "string",
      "Custom Field 2": "string",
      "Custom Field 3": "string",
      "Custom Field 4": "string",
      "Custom Field 5": "string",
      "Custom Field 6": "string",
      "Custom Field 7": "string"
    },
    "DataService": {
      "Plan": {
        "Code": "string",
        "Description": "string",
        "ServiceType": "SMS"
      },
      "ServiceAreas": [
        {
          "Code": "string",
          "Description": "string"
        }
      ],
      "Features": [
        {
          "Code": "string",
          "Enabled": true
        }
      ],
      "DailyTreshold": 0,
      "MonthlyTreshold": 0
    },
    "SMSService": {
      "PlanCode": "string",
      "ServiceAreas": [
        {
          "Code": "string",
          "Description": "string"
        }
      ],
      "FeatureCodes": [
        "string"
      ],
      "DailyTreshold": 0,
      "MonthlyTreshold": 0
    },
    "VoiceService": {
      "PlanCode": "string",
      "ServiceAreas": [
        {
          "Code": "string",
          "Description": "string"
        }
      ],
      "FeatureCodes": [
        "string"
      ],
      "DailyTreshold": 0,
      "MonthlyTreshold": 0
    },
    "CostCenter": "string",
    "State": "Ready",
    "Device": {
      "Identifier": "string",
      "IdentifierType": "IMSI"
    }
  }
]

Setting your callback URL

All operations supported by the M2M API, with the exception of querying for a SIM profile status, are asynchronous by design. Before using any these API, you will want to define a callback URL, allowing you to track the proper execution of your requests.

Sample request

curl -L -X POST 'https://api.enco.io/m2m/1.0.0/configure/callback' \
-H 'Authorization: Bearer {your API Solutions OAUTH2 token}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {your M2M cockpit API key}' \
--data-raw '{
  "url": "{your callback URL}"
}'

Note that this request doesn't return any specific payload.

If your callback URL requires authorization, standard Authentication headers ("Basic" or "Bearer") can be defined as in the following sample request.

Sample request with authorization and custom headers

curl -L -X POST 'https://api.enco.io/m2m/1.0.0/configure/callback' \
-H 'Authorization: Bearer {your API Solutions OAUTH2 token}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {your M2M cockpit API key}' \
--data-raw '{
  "url": "{your callback URL}",
  "headers": {
      "Authorization": "Bearer {callback URL bearer token}",
      "x-test":"Another custom header"
  }
}'

We have implemented a whitelist to allow customization only for the Authorization header, and any header starting with "x-" as to prevent interference with internal systems.

SIM card deactivation

The /requests/deactivation API will deactivate a specific SIM card upon request. You have to include the "x-callback-token" header in the request. It will be set as header when the system posts status updates to your callabck URL. How you want to use this header is entirely up to you. Example usage for this header could be:

• security
• request classification

Sample request

curl -L -X POST 'https://api.enco.io/m2m/1.0.0/requests/deactivation' \
-H 'Authorization: Bearer {your API Solutions OAUTH2 token}' \
-H 'x-api-key: {your M2M cockpit API key}' \
-H 'Content-Type: application/json' \
-H 'Accept-Language: application/json' \
-H 'x-callback-token: encotest' \
--data-raw '[{"identifier":"{your_msisdn}","identifierType":"MSISDN"}]'

The API call will return a tracking number in a json structure. This tracking number can be used to follow-up the status of your request via messages pushed to your callback URL.

Sample API answer payload

{
    "TrackingNumber": "717ccaa0-1234-5678-1234-9444e657ca96"
}

Sample status update message pushed to the callback URL

{
    "trackingNumber": "717ccaa0-1234-5678-1234-9444e657ca96",
    "device": {
        "identifier": "0123456789012345678",
        "identifierType": "ICCID"
    },
    "resultStatus": "Success",
    "messages": []
}

The message above was posted to our callback URL together with the header "x-callback-token" set to "encotest", as defined in our sample deactivation request.

SIM card reactivation

The /requests/reactivation API will reactivate a specific SIM card upon request. You have to include the "x-callback-token" header in the request. It will be set as header when the system posts status updates to your callabck URL. How you want to use this header is entirely up to you. Example usage for this header could be:

• security
• request classification

Sample request

curl -L -X POST 'https://api.enco.io/m2m/1.0.0/requests/reactivation' \
-H 'Authorization: Bearer {your API Solutions OAUTH2 token}' \
-H 'x-api-key: {your M2M cockpit API key}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-callback-token: encotest' \
--data-raw '[{"identifier":"{your_msisdn}","identifierType":"MSISDN"}]'

The API call will return a tracking number in a json structure. This tracking number can be used to follow-up the status of your request via messages pushed to your callback URL.

Sample API answer payload

{
    "TrackingNumber": "717ccaa0-1234-5678-1234-9444e657ca96"
}

Sample status update message pushed to the callback URL

{
    "trackingNumber": "717ccaa0-1234-5678-1234-9444e657ca96",
    "device": {
        "identifier": "0123456789012345678",
        "identifierType": "ICCID"
    },
    "resultStatus": "Success",
    "messages": []
}

The message above was posted to our callback URL together with the header "x-callback-token" set to "encotest", as defined in our sample deactivation request.

API authentication

API Solutions uses OAuth2 to protect API resources. The OAuth2 specification has become the predominant standard for securing RESTful APIs and identity delegation.

In order to gain access to the resources exposed by your API assets, you will need to pass along a valid OAuth2 bearer access token. Here is how you can generate such a token.

Obtaining your OAuth2 Application Keys

Each project you create through the API Solutions Market will result in the creation of a unique pair of OAuth2 application keys. To retrieve your keys, proceed as follows:

• First, log in and visit your dashboard on the portal. Click the "TOKEN" menu.
• This will result in your application keys to be shown. These keys can be used to access API resources exposed by any API asset to which you subscribed, within the scope of the selected project.

Your application keys are sensitive information; keep them private at all time!

Make sure to store your application keys in a safe way, avoiding them to leak or be stolen by an unintended audience. They are quite sensitive, in that anyone obtaining them will be able to gain access to your assets. In case your application keys would become compromised, contact us through support and we'll revoke them to block access, and provide you with a new pair. This is also the reason why all API traffic should pass through secured HTTP, and why we do not support plain HTTP.

Generating a fresh bearer access token

A bearer access token is a self-contained unique identifier through which you can gain access to API resources. Before elaborating on how you can obtain such type of token, please note that these tokens are valid for a limited time span of 1 hour (or less, if explicitly revoked).

You can obtain a new token by issuing the following request against the server https://api.enco.io :

/token POST

Issue a request to https://api.enco.io/token, adding the following headers and body:

Request

curl -X POST \
  'https://api.enco.io/token?grant_type=client_credentials&scope=openid&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&Accept=application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' 

Response payload

{ 
  "scope": "openid", 
  "token_type": "Bearer", 
  "expires_in": {number}, 
  "access_token": {string}
}

The field accesstoken in the response contains your token. The field expiresin will show you the remaining validity of your token, in seconds.

Single active access token
Within the context of a single application, you will only have a single active access token at any time. If you would request a new token using the above request message while the previously issued token has not yet expired, you will get back the previous token. To obtain a new one, revoke the old token; then generate a new one.

Code Samples
To help you getting started on implementing this authentication in your code, you can find some samples on our Github.

Revoking an access token

This procedure should be used when your token has been compromised (leaked, stolen, etc.), or if you want to generate another token, but your old token is still valid.

/revoke POST

Issue a request to https://api.enco.io/revoke, adding the following headers and payload:

Request payload

token=<old-access-token-to-be-revoked>&client_id=<app-consumer-key>&client_secret=<app-consumer-secret>

Creating permanent token

You can create permanent tokens from the "TOKEN" menu of your profile's dashboard. Just click on "Add a new token" to create a new permanent token. Several permanent tokens can be created for the same account.

Your permanent token is sensitive information; keep it private at all time!

Make sure to store your permanent tokens in a safe way, avoiding them to leak or be stolen by an unintended audience. They are quite sensitive, in that anyone obtaining them will be able to gain access to your assets. In case a permanent token would become compromised or not needed anymore, delete this token from your "TOKEN" dashbload by clicking on the red cross next to it.

All set to call your API!

Once a valid access token has been generated, it should be added to request messages. The token should be passed in an HTTP header named Authorization, which should be assigned the value of Bearer, followed by a single space, and immediately followed by the access token. Note the single space between ‘Bearer’ and the token.

curl -i -X GET -H "Accept:application/json" -H "Authorization: Bearer <active-access-token>" https://api.enco.io/lora4maker/0.0.1/device