IXON-API

IXON API documentation

Welcome to the IXON development website. Curious about our API endpoints? Take a look at our endpoint list, you can try-out the API in that section as well. Do you need some guidance on how to use our API? Take a look at the API Documentation. Take a look at our release notes if you're curious what has changed to the API.

Endpoint List    Release Notes

How to use the APIv2?

The APIv2 is the open public API of IXON. It can be used to communicate with your IXrouter, IXagent or your Cloud Logging 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), execute in the IXON Cloud interface what you want to do via the API, and the network log will show you the exact API request, including the endpoint, headers, fields, body, and the response.

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.

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.

🚧

Use the MoreAfter attribute

To make sure you get everything you're asking for, it is strongly recommended to check every API response for the moreAfter attribute. If it has the value 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.

If you need to send a subsequent request, you'll need to add a query argument to your request. You then have to insert "page-after" as the indicator and the 'moreAfter' value behind the URL of your request. Let's say for example you have 30 users in your company, and you only get 20 in your return. You can send the same request with ?page-after={20} as a query argument with the next request. You will then receive users 21-30.

Alternatively, 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. See the snippet below for an example of both options.

curl --request GET \
--url 'https://api.ayayot.com?page-after={MoreAfter value}'
curl --request GET \
--url 'https://api.ayayot.com?page-size={preferred return size}'

expiresIn can be added to set the expiration date for an Authorization token. More information on this can be found in the request bearer token section of this article.

Our reference guide 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.

📘

Public ID

The APIv2 uses different ID’s 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

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 us at [email protected] to get your application ID.

Discovery: Get an up-to-date list of endpoints

The discovery 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. 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 'https://api.ayayot.com' \
--header 'Api-Version: 2'

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 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. This basic authentication string needs to be BASE64 encoded in the request.

Because a bearer token is temporary you also have to include ‘Expires in’ 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:

curl --request POST \
--url 'https://api.ayayot.com/access-tokens?fields=secretId' \
--header 'Api-Version: 2' \
--header 'Api-Application: {applicationId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {Email:OTP:Password}' \
--data '{"expiresIn": 3600}'
{
    "status": "success",
    "type": "AccessTokenCreateResponse",
    "data": {
        "publicId": "{ResonseId}",
        "expiresOn": "2021-02-02T00:59:59Z",
        "secretId": "{Bearer token}",
        "user": {
            "publicId": "{userId}",
            "name": "{username}",
            "emailAddress": "{email adress}",
            "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"
        }
    }
}

Identifying companies and agents

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 'https://api.ayayot.com/companies?fields=publicId,name' \
--header 'Api-Version: 2' \
--header 'Api-Application: {applicationId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {Token}'
{
    "type": "Company",
    "data": [
        {
            "publicId": "{CompanyId}",
            "name": "{company name}"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

Additionally, requests can require further specification for a specific agent (IXrouter or IXagent). You can request all agent ID’s in a company using the AgentList endpoint. To identify the agent we advise to include the fields PublicId, name and device ID. 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 'https://api.ayayot.com/agents?fields=publicId,name,deviceId' \
--header 'Api-Version: 2' \
--header 'Api-Application: {ApplicationId}' \
--header 'Api-Company: {CompanyId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {Token}'
{
    "type": "Agent",
    "data": [
        {
            "publicId": "{agentId}",
            "name": "{agent name}",
            "deviceId": "{MAC} - {Serial Number}"
        }
    ],
    "moreAfter": null,
    "status": "success"
}

Updated 4 months ago


How to use the APIv2?


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.