📘

Required modules

Required module: API Integrations. Check your modules at Admin > Licenses. To obtain this module, contact your IXON account manager or IXON distributor.

📘

Default API URL

By default, IXON Cloud uses the API URL: {user.url}/api/.

📘

API URL for Beijer customers

For Beijer customers, the API URL is: https://cloudvpn.acirroplus.com/api/.

📘

OpenAPI endpoint link

In case you might need to all required metadata, schema definitions, and endpoint details, you can find the OpenAPI specification URL here.

Why use the IXON API?

The APIv2 is the open, public API of IXON; it can help you achieve goals and find solutions tailored to your needs. To get you started, in this article we have explained some important basic steps and functionalities, and we also provide guidence on how to retrieve basic resources, such as an agent, a company, a bearer token but also data sources and tags.

If you want to read more about how these resources are all related to each other, you can take a look at the Guide to Data Mapping in IXON Cloud article.

A few cases in which you would want to use the API are:

• Historical data insights: retrieving Historical data for your own analytics, reporting tools or custom dashboards.

• Seamless integration with other systems: the need to integrate IXON's functionalities with ERPs, CRMs, custom web applications or other SaaS providers.

• Automatization of processes: building custom solutions to automatize various processes related to the router itself, to the management of users or even to data points. Many things that are usually done from the Portal's interfaces can be reproduced via the API (e.g. creation of a new user).

• Retrieve information about your devices:getting information about devices, users, data sources, tags and much more.

👍

What should you use: the API or the App Engine module?

While brainstorming and trying to find a solution to your problem, keep in mind that, if needed, it is possible to use UI Components and Cloud Functions (contained in the App Engine module) together with the API.

For example:

• If you are using UI Components only without needing a Cloud Function (e.g. no backend logic, no DB functionalities, no specific security requirements), you can build an API call using the getApiUrl() function. Check out the Making API Requests article to learn more about it.
• If you are using Cloud Functions (developed with Python) or if want to integrate calls to the IXON API in your own separate project without using the Cloud Functions FunctionContext (you can read more about it in this section), you can build the API call according to the programming language you are using (e.g. Python, UNIX Shell, etc).

API request architecture: Get started with the IXON API

The following subsections contain all the information you need to understand the IXON API's structure and main characteristics: you will learn what the requirements of an API call are as well as basic knowledge that you will need along the way.

Essential prerequisites for a successful API call

The APIv2 supports five types of verbs, namely GET, POST, PATCH, PUT and DELETE, and each request consists of at least a URL and one or more headers. Additionally, fields and filters can be added to get a more organised data response. The APIv2 will respond with JSON or CSV output, depending on the endpoint: for instance, the DataExport endpoint will return a CSV output.

These are the headers that you will be using the most:

• Api Version (the default value is 2)
• Application ID
• Bearer Token
• Company ID

You will learn more details about each one of them in the next sections.

How to identify resources and types: the publicId

The APIv2 uses an ID for many entities, which is more commonly called publicId and which functions as the identifier for agents, data sources, users, groups, alarms, invitation requests and much more.

By using the IXON API, you will notice that a response will nearly always contain at least one publicId, and you might wonder whose publicId that is. Keep reading to find out how to figure it out.

How to find the right publicId

In most JSON responses, there is always a field called type. This fields determines what kind of entity the ID belongs to. For example, the publicId in a response with type "Company" means that this publicId is a "companyId".

👍

IXON Trivia: the "List" endpoints

If you take a look at our API Reference page, you may notice how many endpoints seem to have a "List" counterpart. Let's take, for example, the Agent and AgentList endpoints. What are the differences between them?

• The former (in this case Agent) is mainly used in use cases where recovering just one entity of that type of resource is enough. For example, this endpoint is called whenever a user clicks on a specific agent in Fleet Manager > Devices.
• The latter (in this case AgentList) is instead used whenever an action has to be performed on a list of entities having that resource type. The path to your Devices that we mentioned in the previous point is a clear example of this since it retrieves a list of agents.

How to find the complete list of the IXON API endpoints

Our Endpoint Documentation page contains an up-to-date list of all endpoints and the headers, fields, filters, and body parameters that you can add to the request. The reference guide can also give a preview of responses, and gives you the option to try a request. Samples of some common programming languages are supplied by the reference guide as well.

👍

Tip: How to find an API request/response in your browser

A practical source of information is the IXON Cloud itself. Open your browser's DevTools (F12), open the Network tab and execute in the IXON Cloud interface what you want to do via the API. The network log will show you the exact API request, including the endpoint, headers, fields, body, and the response. You can create an overview of all API requests by selecting the type XHR and filtering on {user.url}/api. You can also use the Web Inspector to select the item that will take you to the correct API.

🚧

Note: Not all endpoints can be used externally!

Some endpoints included in the API reference page are not intended for any use outside of IXON's internal logic, and therefore we recommend against implementing them in your own logic, flow or system.

How to visualize your data in a JSON response

Some API responses will not return everything you asked for in a single response and thus require you to send subsequent requests. For example, when requesting a list of your devices, you may only get up to 20 devices in the API response, while you may have more.

How to use the moreAfter and page-after attributes to get a full list of data

To make sure you get everything you're asking for, it is strongly recommended to check every API response for the moreAfter attribute. Note that if the value is null you received the full list in the first response.

Example

You have 30 users in your company, and you will only get 20 in your return of the first call. To see the rest, you will need to grab the value of moreAfter, and then you can send the same request with as a query argument with the next request. You will then receive users 21-30.

This workflow retrieves a full list of Users. We are assuming that the list is made out of more than 20 users:

• Request the retrieval of a list of Users and copy the value of the moreAfter field. Usually, you can find it at the end of the JSON Response.

• Send another request to UserList by adding the value of moreAfter to the page-after query argument. You may need to repeat this multiple times in case your list is very long.

  page-after

  curl --location "https://portal.ixon.cloud/api/users?fields=*&page-after=$moreAfterValue" \
  --header 'Api-Version: 2' \
  --header "Api-Application: $applicationId" \
  --header "Api-Company: $companyPublicId" \
  --header "Authorization: Bearer $bearerToken"

Please note: the ? is used for the first query argument. Consequent arguments would need the &, for example {user.url}/api/endpoint?attribute=value1,value2&page-after=moreafter_value.

🚧

Exception

The DataList endpoint is an exception to this, because moreAfter will then always be null. For more information, see Understanding historical data.

How to use the page-size attribute to get a full list of data

To get more data, it is possible to get a larger response by using the page-size attribute, followed by the amount of required returns. This option is limited to a maximum of 4000 returns. See the following example snippet:

curl --location '{user.url}/api/users?fields=*&page-size=3' \
--header 'Api-Version: 2' \
--header "Api-Application: $applicationId" \
--header "Api-Company: $companyPublicId" \
--header "Authorization: Bearer $bearerToken"

How to use page-size, page-after and the value of moreAfter to get a full list of data

If you so desire, you can use page-size together with page-after and the value of moreAfter to visualize even more data without having to run more requests. In this case, use another & to separate the two fields, like such: ?attribute=value1,value2&page-size=3&page-after=$moreAfterValue. See the code snippet below for an example:

curl --location "https://portal.ixon.cloud/api/users?fields=*&page-size=3&page-after=$moreAfterValue" \
--header 'Api-Version: 2' \
--header "Api-Application: $applicationId" \
--header "Api-Company: $companyPublicId" \
--header "Authorization: Bearer $bearerToken"

How to request an Application ID

All endpoints can solely be reached when a valid Application ID is provided. Therefore, when you want to use the APIv2 you need to request an Application ID first. Please, contact your Sales representative to get started with our API.

📘

Using both API1 and API2

The same Application ID can be used for API1 and API2.

How to request a bearer token

Most endpoints require authentication. By using bearer tokens, your requests will be processed more quickly and safely compared to storing your password. To request one, you have to use the AccessTokenList endpoint.

We recommend to use Postman or another similar tool for the following steps.

Step 1 - Get Basic Authorization

To set up the Authorization section of this call, select Basic Auth as Auth Type and then add {{email}}:{{2fa}} in the Username section and {{password}} in the Password section. You can fill these environmental variables with the respective values by hovering over them.

Please note: the {{2fa}} field isn't needed unless you are using Two-Factor Authentication (the field will be highlighted in red), in which case you will have to recover a valid code, set it up in its field and then send the request before its expiration. You should therefore leave it empty. Here is an example of what the section should look like:

Alternative: Get Basic Authorization via Shell

As we mentioned before, an example of a case scenario in which you want to use the API would be automatizing a process with custom code, for example using a Shell script. This process would require the generation of a bearer token, and therefore also of Basic Authorization.

To set up Basic Auth in a Shell script you need to manually generate a cipher of your credentials. Before encrypting, this string consists of your email address and your IXON Cloud password, so the value to encrypt would be $yourEmailAddress::$yourPassword.

$(echo -n '[email protected]::Password1' | base64)

Note that if you make use of Two-Factor authentication you need to include the One Time Password (OTP) as well. The string needs to be BASE64 encoded in the request and uses the format: $yourEmailAddress:$yourOtp:$yourPassword (check the note below for additional information).

🚧

Tip:

We do not recommend using this method if you use Two-Factor Authentication. If you are not fast enough, the OTP might expire before you can successfully use it to get the encrypted string, copy it into the cURL command and get a successful request. If you are not building a script, it is easier to use a tool like Postman and set up environment variables instead. On the contrary, if you are building a script, we suggest creating a user created specifically to call the API without any enforced 2FA.

Step 2 - Set an expiration time and get the secretId field

Because a bearer token is temporary you also have to include ‘expiresIn’ data in seconds. You can choose an expiration time between 60 seconds and 60 days (5.184.000 seconds). In the request, you have to include the field 'secretId' in the URL: this is the value of the bearer token, which you will be using whenever required. This value will be composed of 32 characters in total, among which you can find capital letters, lower case letters and numbers. The examples below contain a request for a bearer token and its response using the AccessTokenList endpoint.

curl --request POST \
     --url '{user.url}/api/access-tokens?fields=secretId' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $applicationId" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Basic $base64_cipher_of_credentials" \
     --data '{"expiresIn": 3600}'

{
    "status": "success",
    "type": "AccessTokenCreateResponse",
    "data": {
        "publicId": "$responsePublicId",
        "expiresOn": "2021-02-02T00:59:59Z",
        "secretId": "$bearerToken",
        "user": {
            "publicId": "$userPublicId",
            "name": "$username",
            "emailAddress": "$userEmailAddress",
            "support": false,
            "language": "en",
            "localisation": null,
            "timeZone": null,
            "registeredOn": "2020-09-01T10:59:29Z",
            "lastSeenOn": "2020-12-02T07:38:31Z",
            "termsOfUsePolicyAcceptedOn": "2020-09-01T10:59:29Z"
        }
    }
}

Step 3 - Use a bearer token with its correct syntax

The syntax of the bearer token might be source of confusion, which will be cleared up in this section.

❗️

Important premise

It is nearly always assumed that the correct syntax would be a concatenation of the following: Bearer+bearer_value (secretId) . In the following use example, Bearer already specifies for us that the Auth Type is of "Bearer" type, therefore all you have to do next is to insert the actual value of the previously recovered secretId. You will need to add Bearer when it is not specified anywhere else, like inside the body of the cURL request below: --header 'authorization: Bearer A9dP3vXzR7qLmF2HsTkW0jCeUyNb8GoV.

If you want to make an API call from our endpoint list section you will need to fill in the Credentials section on the right by adding the value of the secretId that you generated with the AccessTokenList call. If the value of the secretId is Abc93vXzR7qLmF2HsTkW0jCeUyNb8GoV, then you will only insert this part in the box below. See AgentDataSource to follow this example.

Environmental variables in Postman

In case you want to use Postman without importing a cURL command, or in case you want to manually modify the settings of an API call, you can set up an environmental variable and assign your bearer token to it. After that, go to the Authorization section, select "Bearer Token" as Auth Type on the left, and once you will type the name of the variable between mustache tags as shown below, you should see the following by hovering over it:

As you can see, the "Bearer" type is being pre-declared by Postman, and all you need to add is the value.

👍

Note

Keep in mind that on Postman, if you declare the bearer token in the Authorization section, you won't need to declare it in the Headers section.

The Discovery endpoint: How to get an up-to-date list of endpoints

The Discovery endpoint serves as a starting point to 'discover' the other endpoints and their URLs. In your code, a request to the discovery should be made before the other endpoints are accessed.

Every endpoint object will be return:

• A href, which consists of the URL itself.
• A rel, which consists of the 'nickname' of the endpoint, which also works as its identifier.

Recommended workflow

To avoid hard-coding URLs in your projects and therefore running into problems in case the URL is changed, we advise that you retrieve the URLs that you need via the Discovery endpoint. You can see how this is done by checking out a tutorial in the IXON API Code Tutorials macro-section.

To recover an endpoint make sure to use the rel field in your code, and based on that retrieve the href field belonging to it. This will return the most up-to-date URL from the discovery endpoint. An example of how to make a request to the discovery endpoint is given below:

curl --request GET \
     --url '{user.url}/api/' \
     --header 'Api-Version: 2'

{
  "type": "Discovery",
  "data": [
    {
      "rel": "AccessRecoverList",
      "href": "https://portal.ixon.cloud/api/access-recover",
      "methods": [
        "GET",
        "POST"
      ]
    },
    {
      "rel": "AccessTokenList",
      "href": "https://portal.ixon.cloud/api/access-tokens",
      "methods": [
        "GET",
        "POST",
        "PATCH",
        "DELETE"
      ]
    }
  ],
  "moreAfter": $moreAfterValue,
  "status": "success"
}

How to get a company's publicId

All users and agents in the IXON Cloud are part of a company. To help identify what agents and/or users you are requesting information for, many requests require a company ID. The CompanyList endpoint will return all companies that you have access to, including their publicId. Examples of the request and response, including the required headers, for a company ID are displayed below:

curl --request GET \
     --url '{user.url}/api/companies?fields=publicId,name' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $applicationId" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearerToken"

{
    "type": "Company",
    "data": [
        {
            "publicId": "$companyPublicId",
            "name": "$companyName"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

How to get an agent's ID

Additionally, requests can require further specification for a specific agent (IXrouter or IXagent). You can request all agent IDs in a company using the AgentList endpoint. To identify the agent we advise to include the fields publicId, name and deviceId. This way the name of the agent and the MAC address/Serial Number are included as well. Examples of the request and response, including the required headers, for a company ID are displayed below:

curl --request GET \
     --url '{user.url}/api/agents?fields=publicId,name,deviceId' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $applicationId" \
     --header "Api-Company: $companyPublicId" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearerToken"

{
    "type": "Agent",
    "data": [
        {
            "publicId": "$agentPublicId",
            "name": "$agentName",
            "deviceId": "$macAddress - $serialNumber"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

🚧

Difference between an agent's publicId and its deviceId

• A publicId of an agent is the main identifier used after the router's registration. It's used to connect the agent to the VPN, to retrieve or send data, and more. This is what it looks like: 9MuFepQeCJWL.
• A deviceId corresponds to the ID of the actual hardware device, and it's used during its registration. It's composed by the MAC address and the Serial Number of the hardware. For example: C0:D3:91:31:A6:49 - 17077319.

Use cases

In these subsections you will find a few examples and use cases using the IXON API.

How to access data sources and tags of an agent

Once you have identified the agentId, you can use it to query for a list of data sources and a list of tags through the AgentDataSourceList and AgentDataTagList endpoints respectively.

What you will need:

• Your companyId.
• Your applicationId.
• Your bearer token.

The information you will obtain can in turn be used to query historical data and more. For more information see Understanding historical data, and for a full code implementation check out our How to retrieve historical data using the DataList endpoint tutorial.

Data sources

Refer to this example to retrieve data sources:

curl --request GET \
     --url "{user.url}/api/agents/$agentId/data-sources?fields=publicId,name" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $applicationId" \
     --header "Api-Company: $companyPublicId" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearerToken"

{
    "type": "AgentDataSource",
    "data": [
      {
        "publicId": "$dataSource1PublicId",
        "name": "$dataSource1Name"
      }, 
      {
        "publicId": "$dataSource2PublicId", 
        "name": "$dataSource2Name"
      }
    ], 
    "moreAfter": null, 
    "status": "success"
}

Tags

Refer to this example to return all data tags from all data sources that are configured on an agent:

curl --request GET \
     --url "{user.url}/api/agents/$agentId/data-tags?fields=publicId,name,tagId,slug" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $applicationId" \
     --header "Api-Company: $companyPublicId" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearerToken"

{
    "type": "AgentDataTag", 
    "data": [
      {
        "publicId": "$tagPublicId", 
        "tagId": 2, 
        "name": "$tagName",
				"slug": "$slugName"
      }, 
      {
        "publicId": "$tagPublicId", 
        "tagId": 4, 
        "name": "$tagName",
				"slug": "$slugName"
      }, 
      {
        "publicId": "$tagPublicId", 
        "tagId": 1, 
        "name": "$tagName",
				"slug": "$slugName"
      }, 
      {
        "publicId": "$tagPublicId", 
        "tagId": 1, 
        "name": "$tagName",
				"slug": "$slugName"
      }, 
      {
        "publicId": "$tagPublicId", 
        "tagId": 3, 
        "name": "$tagName",
				"slug": "$slugName"
      }, 
      {
        "publicId": "$tagPublicId", 
        "tagId": 2, 
        "name": "$tagName",
				"slug": "$slugName"
      }
    ], 
    "moreAfter": null, 
    "status": "success"
}

👍

Note about slugs

"Slug" is just another way to call a variable's identifier. A quick way to find it is by going to Fleet Manager > Devices > Device of choice > Data sources > Data source of choice > Tags and taking a look at the value in the identifier field:

In general, as shown above, a slug/identifier consists of the Tag name written in lowercase with a dash separating each word (instead of camel-case or a space).
The "tagId is, instead, the identifier used in the time-series database. If you won't be using functionalities related to direct InfluxDB access, you most likely will not need to use it.

Where to find more use cases

If needed, you can consult the following sections/articles to find more how-tos and use cases:

• Use cases for managing groups, users, roles.
• Use cases for managing devices.
• Use cases for managing assets (more information coming soon).
• Use cases for managing custom fields.
• Use cases for managing access requests.
• Use cases for managing MQTT Brokers and their clients.