IXON API prerequisites (APIv2)
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
XHRand 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. 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. Follow these steps to obtain it:
Step 1 - Get Basic Authorization
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.
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. You should therefore leave it empty.
Here is an example of what the section should look like:
Step 2 - Set an expiration time and get the secretId field
secretId fieldBecause 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.
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"
}
}
}
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,Beareralready specifies for us that the Auth Type is of "Bearer" type, therefore all we have to do next is to insert the actual value of the previously recoveredsecretId. We will need to addBearerwhen 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.
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:
Once again, 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 Header section.
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
publicIdin 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:
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
nullyou 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
moreAfterwill then always benull. 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 8 days ago