Accessing the Mender API with NodeJS - PAT version

Tutorials
, ,
1

Introduction

The Mender backend follows an API first philosphy. This means all functionality is exposed through documented endpoints, and you are invited to use those to match and implement your custom flows.

In this short tutorial, I will show you how to access the API from a NodeJS script using a personal access token. For more in-depth information on the API, check out the documentation and the API reference.

Prerequisites

To follow the examples you need the following:

  • a Hosted Mender account. We will use the US instance, but adapting to the EU one is straightforward. You can sign up here
  • the NodeJS runtime being installed

Tutorial

Step 0: Project setup

We will create a project named mender-api-demo using generic NodeJS practises.

mkdir mender-api-demo
cd mender-api-demo
npm init -y

For simplicity, we will use the axios library to do the API calls. Add it to the project:

npm i --save-prod axios

Now open a new file index.js in the editor of your choice, and add the line

const axios = require('axios');

to load the axios library. Then you’re ready to go!

Step 1: Authentication - generating personal access token (PAT)

NOTE: this is not possible for accounts which are using a SSO login such as Google or Microsoft currently

Log into your Mender dashboard and open the “My profile” view. This is the second entry in the dropdown menu which appears when you click your mail address in the top right corner.

In “Personal access token management” section, click “Generate a token”. This opens a dialog to define name and expiration. The permission level is tied to your user permissions.

Screenshot 2024-01-17 at 14.43.14
Screenshot 2024-01-17 at 14.43.141460×688 42.5 KB

Once finished, click “Create Token”

The generated token is then displayed in a following view. Copy it to your clipboard and store it to a permanent place, as it cannot be shown again. If you lose the token, you need to revoke it and create a new one.

Screenshot 2024-01-17 at 14.44.09
Screenshot 2024-01-17 at 14.44.09982×1550 182 KB

Step 2: API access

We will call the device list API endpoint to receive a list of devices accepted on our account. Please note that the endpoint is paginated, so if you have a large number of devices then the returned array will not be exhaustive.

Add the following code to index.js, and insert your PAT into the jwt constant assignment:

const jwt = "...."; // paste your token here!

axios({
    method: 'GET',
    url: "https://hosted.mender.io/api/management/v1/inventory/devices",
    headers: {
      'Accept': 'application/json',
      'Authorization': 'Bearer ' + jwt,
    }
  });
})
.then((response) => {
  console.log("received device list: " + JSON.stringify(response.data));
})
.catch((error) => {
  console.log("error" + error);
});

This prints a list including an extensive list of details on each device - the inventory - to the console.

Congratulations, you have just successfully called the Mender server API!

Next steps and conclusion

You are now perfectly equipped to start using the Mender API for your custom logic. Some ideas to explore:

  • uploading artifacts
  • creating deployments
  • gathering statistics

By exposing and documenting all facets of the API, the Mender backend offers both high customizability and anti-lock in, as you can replace each part as needed. Web frontend, backend, none or both.

What did you build? Let us know in the comments!