| Developer Documentation
Documentation
Support SiteRoadmapStatus PagePrivacy

IXON API prerequisites (APIv2)

Suggest Edits

📘

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: <<url>>/api/.

📘

API URL for Beijer customers

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

The APIv2 is the open, public API of IXON. It can be used to communicate with your IXrouter, IXagent or your Historical data. The APIv2 allows you to integrate IXON's functionalities and data seamlessly with other IT systems. This way you can maximize your business value with IXON. To get you started we have explained some important basic steps and functionalities in this article.

API request architecture

👍

Development tip

A practical source of information is the IXON Cloud itself. Open your browser's network log (F12) 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 <<url>>/api. You can also use the Web Inspector to select the item that will take you to the correct API.

The APIv2 supports five types of requests: GET, POST, PATCH, PUT and DELETE. 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.

Our Endpoint Documentation page contains an up-to-date list of all endpoints and the headers, fields, filters, and body parameters 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.

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.

Request a bearer token

Most endpoints require authentication. You can use basic authentication, which consists of your login credentials of the IXON Cloud. We advise you to switch to using a bearer token after the first request, because your requests will be processed more quickly and it's also safer than storing your password.

You can request a bearer token with the AccessTokenList endpoint. To get authorization, you need to add a header with Basic Authorization, which includes a cipher of your credentials. Before encrypting, this string consists of your email address and your IXON Cloud password. If you make use of Two-Factor authentication you also need to include the One Time Password (OTP) as well. The string needs to be BASE64 encoded in the request and uses the format: emailaddress:OTP:password. Without an OTP, the value to encrypt would be: emailaddress::password. 

$(echo -n 'emailaddress::password' | base64)

🚧

Tip:

We do not recommend using the aforementioned bash command 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! In that case, it is easier to use a tool like Postman and set up environment variables as shown in the green note below.

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). To make it easier to identify the bearer token you can include the field 'secretId' in the body, this is the name of the bearer token in the response. The examples below contain a request for a bearer token and the response and the required variables.

curl --request POST \
     --url '<<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": "$response_id",
        "expiresOn": "2021-02-02T00:59:59Z",
        "secretId": "$bearer_token",
        "user": {
            "publicId": "$user_id",
            "name": "$username",
            "emailAddress": "$email_address",
            "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"
        }
    }
}

👍

Using Postman to generate a credentials cipher

It is possible to set up the Authorization section of this call by selecting Basic Auth as Auth Type and then adding {{email}} and {{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.
Here is an example of how the section should look:

Get an up-to-date list of endpoints

The Discovery endpoint serves as a starting point. Typically, a request to the discovery is made before the other endpoints are accessed: it serves as an entry point to 'discover' the other endpoints and their URLs. Endpoints will be returned as both a URL and a rel.
Please note: it is recommended to use the rels in your code, and then add the most up-to-date URL from the discovery endpoint, because the URLs may be changed over time. An example of how to make a request to the discovery endpoint is given below:

curl --request GET \
     --url '<<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"
}

📘

Public ID

The APIv2 uses different IDs for many entities. In the JSON response, there is always a row called “Type”. This will identify what kind of ID that specific public ID is. For example, the publicId in a response with type "Company" means this publicId is a "companyId".

Get company IDs

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 public ID. Examples of the request and response, including the required headers, for a company ID are displayed below:

curl --request GET \
     --url '<<url>>/api/companies?fields=publicId,name' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

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

Get agent IDs

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 device 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 '<<url>>/api/agents?fields=publicId,name,deviceId' \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

{
    "type": "Agent",
    "data": [
        {
            "publicId": "$agent_id",
            "name": "$agent_name",
            "deviceId": "$mac_address - $serial_number"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

How-To Example: access data sources and tags with retrieved data

Once you have identified the agentId, you can use it to query for data sources and tags through the AgentDataSourceList and AgentDataTagList endpoints respectively. Needless to say, you will also need your companyId, applicationId and bearer token. The information you will obtain can in turn be used to query historical data and more. For more information see How to use historical data?.

Data sources

curl --request GET \
     --url "<<url>>/api/agents/$agent_id/data-sources?fields=publicId,name,ipAddress" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

{
    "type": "AgentDataSource",
    "data": [
      {
        "publicId": "$public_id_datasource1",
        "name": "$name_datasource1"
      }, 
      {
        "publicId": "$public_id_datasource2", 
        "name": "$name_datasource2"
      }
    ], 
    "moreAfter": null, 
    "status": "success"
}

Tags

curl --request GET \
     --url "<<url>>/api/agents/$agent_id/data-tags?fields=publicId,name,tagId,slug" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $bearer_token"

{
    "type": "AgentDataTag", 
    "data": [
      {
        "publicId": "$public_id_tag", 
        "tagId": 2, 
        "name": "$tag_name",
				"slug": "$slug_name"
      }, 
      {
        "publicId": "$public_id_tag", 
        "tagId": 4, 
        "name": "$tag_name",
				"slug": "$slug_name"
      }, 
      {
        "publicId": "$public_id_tag", 
        "tagId": 1, 
        "name": "$name_tag",
				"slug": "$slug_name"
      }, 
      {
        "publicId": "$public_id_tag", 
        "tagId": 1, 
        "name": "$name_tag",
				"slug": "$slug_name"
      }, 
      {
        "publicId": "$public_id_tag", 
        "tagId": 3, 
        "name": "$name_tag",
				"slug": "$slug_name"
      }, 
      {
        "publicId": "$public_id_tag", 
        "tagId": 2, 
        "name": "$tag_name",
				"slug": "$slug_name"
      }
    ], 
    "moreAfter": null, 
    "status": "success"
}

📘

Note:

The AgentDataTagList endpoint will return all data tags from all data sources that are configured on an agent.

👍

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 > $yourDevice > Data sources > $yourDataSource > Tags and taking a look at the value in the identifier field:

tags-picture

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

Data visualization: the moreAfter attribute

Some API responses will not return everything you asked for in a single response and thus require you to send subsequent requests.
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!

To make sure you get everything you're asking for, it is strongly recommended to check every API response for the moreAfter attribute:

  • If the value is null you received the full list in the first response;
  • If it contains a value instead, then you'll need to send another request to get everything (details below). You may need to repeat this multiple times.

🚧

Exception

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

Therefore, for a subsequent request, you'll need to add the page-after query argument to your request. You then have to insert the value of moreAfter (which you can find at the bottom of the response JSON) behind the URL of your request.
Example: if 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 ?page-after={moreAfterValue} as a query argument with the next request. You will then receive users 21-30.
Please note that the ? is used for the first query argument. Consequent arguments would need the &, for example <<url>>/api/endpoint?attribute=value1,value2&page-after=moreafter_value.

Another alternative: you can request a larger response by using the page-size attribute, followed by the amount of required returns. It is still strongly recommended to check the moreAfter attribute in API responses, just in case you get back more than you anticipated. This option is limited to a maximum of 1000 returns.

Yet another alternative: if you so desire, you can also use both at the same time! In this case, use another & to separate the two fields, like such: ?attribute=value1,value2&page-size=3&page-after=$moreAfter_value.

See the cURL snippets below for an example of each of the three options.

curl --location '<<url>>/api/users?fields=*&page-size=3' \
--header 'Api-Version: 2' \
--header "Api-Application: $applicationId" \
--header "Api-Company: $companyId" \
--header "Authorization: Bearer $bearer_token"

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

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

Updated 1 day ago