Getting Started with the AMM API

This is an overview of how you can use the AMM API.

Before proceeding with using the AMM API, it is highly recommended that the AMM is upgraded to 2.17.5+, so that all the developed API features are available. If you are using an AMM version previous to 2.17.5, please review the release notes as to any API feature exceptions.

Initializing Table Of Contents...

Basics

What can you do with the API?

The AMM API provides a powerful and flexible interface between deployed devices and AMM. It enables you to develop custom applications tailored to your business needs, whether for smartphones, CRM systems, ERP platforms, or other domains.

For example, you can use the API to:

Exploit raw applicative data and aggregated fleet data.
Remotely monitor and manage devices to avoid field intervention.

Flowchart process

The steps to use the AMM API are as follows:

Decide on what REST client to use
Define the API user and privileges on the AMM
Setup the API client
Define the API Usage Limits
Obtain an Access Token
Make the API call by sending the request using the API client
Receive the response from the AMM server
Error handling

Which tool can you use?

Start by installing a REST Client. The two supported tools are :

Postman can be used to test your API calls with AMM
cURL can also be used to transfer data.

When using HTTPS, it is recommended to use a valid CA-signed certificate with a complete certificate chain. Otherwise, the connection may result in errors or require the use of the -k option in curl (or equivalent) to avoid exceptions, which can expose you to security risks. In Postman, you can disable self signed errors.

Create an API User

In order to be able to define an API client, an end user must be created with select Develop privileges defined under Tabs:

Develop > API Clients
Develop > API Monitoring

This end user should be created with the least amount of privileges.

The following permissions should not be granted to end users, as they are administrative actions that can affect the performance of the AMM.

Develop > API Group Usage Control

Develop > API User Access Control

Refer to Creating an AMM user for more information.

Depending on the AMM version and features, certain special privileges are not included under the All tab and must be explicitly granted. As an admin, you can create a new user or modify an existing one to assign these permissions. To do this, uncheck the All checkbox for Tabs and manually grant the required permissions. Note that special permissions marked with a * prefix can only be granted by users who already have those specific permissions.

Create an API Client

The API Client represents the identity of the application that needs to connect to the AMM API. All the API calls will be traced and related to an API Client. To create an API client :

Go to Develop > API Clients
Click on the Add action
Select the Customer Group that the API client is assigned to
Enter a Client Name
Enter the Redirect URL: Enter the URL where the user should be redirected after authorization (essential for the Authorization Code flow).
Select Access Enabled : this will activate the API client
Optionally enter a Description.

The AMM will generate a unique client ID and secret key for this client. These credentials are required for authentication.

For more information on creating an API Client, refer to API Client.

API Rate Limits

The AMM implements rate limits to manage API usage and prevent resource exhaustion. Recommended API configuration is as follows:

Configuration	Value
Request Timeout	Leave it at default 300 seconds
System Wide Rate Limit	Leave it at default 10,000 requests/hour
Owner Group Rate Limit	Leave it at default 360 requests/hour
Number of Clients	Maximum 20
API Client(s) per Owner Group	1

Near realtime or frequent polling intervals may be difficult to implement for large fleets. Setting the polling interval to 5,10 or 30 minutes for each gateway or group is advisable.

For more information on adjusting rate limits, refer to API Group Usage Control.

Obtain an Access Token

To integrate to AMM APIs, you will first need to authenticate. This requires:

An API Client identifier
Support for one of the OAuth Flow methods described below

User credentials are not sent in plain text. By default, all API communication to the AMM server uses HTTPS. It is not recommended to use HTTP.

Implement authentication

AMM uses the OAuth 2.0 protocol for authentication. AMM supports three ways of getting an access token. Select the flow that best suits your application:

The Authorization Code Flow: This should be the preferred flow for server-side applications. This flow is great if your code can keep a secret. The application will get an access token and a refresh token. The refresh token can then be stored by the application and used later to get a new access token without asking the user again for credentials.
The Resource Owner Flow: This flow can be used if the user trusts the application e.g. you are a company and you’re developing an application only used by your employees, then they don’t need to give their credentials to the application.
The Implicit Flow: This flow is designed for client-side web applications (single-page apps) that cannot securely store client secrets. It allows the application to directly receive an access token from the authorization server via a redirect, bypassing the need for an intermediate authorization code.

You can find more details about how authentication works as well as sample API calls in this AMM API documentation section .

Specs: rfc6749

Get an Access Token

The method depends on which Oauth flow method your application uses. Following examples use Resource Owner Flow:

Using Postman (Resource Owner Flow)

Open Postman and create a new POST request.
Set the request URL to https://<AMM IP address>/api/oauth/token.
Go to the Authorization tab and select Basic Auth.
Enter your API client ID as the username and the secret key as the password.
In the Body tab, select x-www-form-urlencoded and add the following key-value pairs:
- grant_type: password
- username: AMM API user name
- password: AMM API user password
Select Send to make the request.
If successful, the response body will contain the access token, refresh token, expiry time, and scope.

This is how it looks in Postman:

Using curl (Resource Owner Flow)

curl -X POST \
  https://<AMM IP address>/api/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic <Base64 encoded client_id:client_secret>' \
  -d 'grant_type=password&username=<AMM API user name>&password=<AMM API user password>'

Replace <AMM IP address>, <Base64 encoded client_id:client_secret>, <AMM API user name>, and <AMM API user password> with the actual values.
A successful response will be in JSON format and include the access token.

Tokens are your own property and responsibility: Never share a token with anyone or between two applications. For example, don’t share it in a public source repository.

Access Token Usage

The client accesses protected resources in AMM by presenting the access token.

The method in which the client utilizes the access token to authenticate with the AMM involves using the HTTP “Authorization” request header field [RFC2617].

For example, replace {accessToken} by your access token in the Authorization header:

GET https://<AMM IP address>/api/v1/applications 
Authorization: Bearer {accessToken}

Why you must not use a token as a parameter...

Another possibility is to send the access token in the HTTP request URI, where the client adds the access token to the request URI query component. However, its use is not recommended, due to its security deficiencies.

For example:

https://<AMM IP address>/api/v1/applications?access_token={accessToken}&name=myApplication

Because of the security weaknesses associated with the URI method, including the high likelihood that the URL containing the access token will be logged, it SHOULD NOT be used unless it is impossible to transport the access token in the “Authorization” request header field.

Make an API call

Once you have created the API Client and picked the most appropriate OAuth2 flow for your application, you can start calling AMM API using the language of your choice (Java, Javascript, Ruby, Python…).

AMM provides all the features in its API, making it really easy to integrate with your backend to automate your flows.

Have a look at the API & Examples page to find API Libraries in several languages to illustrate what will be described below.

Getting Gateway Information

First, you need to get your gateway information. One of the most important fields is the uid which is used by the API to identify your gateway. The uid is the gateway ESN. If you don’t know the uid, you can retrieve it using the following command:

Get information about your gateways, using the API:

> GET https://<AMM IP address>/api/v1/systems?heartbeat=1440&platforms=MG90,GX440,LX60,MP70

Using Postman:

Create a new GET request
Set the request URL to https://<AMM IP address>/api/v1/systems
In the Authorization tab, select Bearer Token and provide the access token you obtained.
In the Body tab, select x-www-form-urlencoded and add the following key-value pairs.
- heartbeat: 14400
- platforms: MG90,GX440,LX60,MP70
Select Send.
The response will contain a hierarchical list of gateways configured in your AMM.

Using curl:

curl -X GET -H 'Authorization: Bearer <access token>' \
  'https://<AMM IP address>/api/v1/systems?heartbeat=14400&platforms=MG90,GX440,LX60,MP70' \

Copy the uid field for the specific gateway from the response below:

{
   "All gateways": [{
      "My MG90 devices": [
         {
            "uid": "ND6123999011020",
            "name": "my MG90 A"
         }, {
            "uid": "ND90410999011035",
            "name": "my MG90 B"
         }]
      }, {
      "My ALEOS devices": [
         {
            "uid": "CA13999002410",
            "name": "my GX440"
         }, {
            "uid": "WM80520999021016",
            "name": "my LX60"
         },{
            "uid": "N655119991021018",
            "name": "my MP70 A"
        }, {
           "uid": "N660940999011023",
           "name": "my MP70 B"
        }]
      }, {
         "uid": "ND90410999011039",
         "name": "my unregistered MG90"
      }
   ]
}

GETting the latest stats for your gateway

Once you can identify your gateway, you are ready to get data values from it.

To get the latest location and heartbeat information from a gateway:

> GET https://<AMM IP address>/api/v1/systems/<uid>/data?ids=ReportIdleTime,GPS Location-latitude,GPS Location-longitude

Using Postman:

Create a new GET request
Set the request URL to https://<AMM IP address>/api/v1/systems//data
In the Authorization tab, select Bearer Token and provide the access token you obtained.
In the Params tab add the ids parameter with a comma-separated list of stats you want to retrieve. For example: ids=ReportIdleTime,GPS Location-latitude,GPS Location-longitude
Select Send.
The response will show the latest location coordinates and the idle time, which can be interpreted as a heartbeat indicator.

Using curl:

curl -X GET -H 'Authorization: Bearer <access token>' \
  'https://<AMM IP address>/api/v1/systems/<uid>/data?ids=ReportIdleTime,GPS Location-latitude,GPS Location-longitude' \

Below is an example of what you could see.

{
   "ReportIdleTime": [{
      "value": "2796808",
      "timestamp": 1581500240000
   }],
   "GPS Location-latitude": [{
      "value": "49.273376",
      "timestamp": 1579136926000
   }],
   "GPS Location-longitude": [{
      "value": "-123.103834",
      "timestamp": 1579136926000
   }]
}

Error Handling

The AMM API uses standard HTTP status codes to indicate the outcome of a request. Understanding these codes and their corresponding messages is essential for effective error handling in your applications.

For more details, see AMM API Error Handling

All set!

Now that you can get data from AMM, you can create charts, tables, show alerts in your custom application using the API. For more details, see AMM API Reference

Now you’re ready to go further and develop features such as:

Web applications to display your business data
Mobile applications to control your devices from your smartphone
Your own business dashboards using existing tools
Integration in your IT
Integrations with other online services like Salesforce, Zoho, Zapier, etc

More resources

Also take a look at the API Libraries & Examples to find more sample applications!

Matching results