What is a Service Account?

Service Accounts are non-personal "accounts" that let external IT applications communicate securely with the IXON Cloud API via an application ID and a permanent access token tied to it. Using a Service Account is the recommended way to authenticate an API integration.

Advantages of Service Accounts

• No email, password or 2FA needed: the token isn't tied to personal login credentials, so there are none to provide, rotate or store.

• Unlimited creation: you can create as many as you like — ideally one per integration, so you can revoke or re-scope a single integration without touching the others.

• Configurable role: Service Accounts are created with an Administrator role by default, but access can be restricted. Give each one only the permissions its integration actually needs.

• No expiration: unlike user access tokens from the AccessTokenList endpoint, Service Account access tokens do not expire. There's no renewal logic to build.

• Business continuity: if the user who originally created the Service Account is deleted or leaves the company, the Service Account remains active.

• Service Accounts for end customers: machine builders can extend Service Accounts to their end customers, giving them isolated access to their own devices.

Limitations of Service Accounts

Service Accounts cannot be used for integrations of IXON Cloud functionalities that require human credentials.

Below you can find a list of these limitations:

• The following functionalities and their related endpoints are not supported:

  • Access Requests cannot be approved or rejected. Requests for connections protected by Access Requests are automatically denied.
  • Message Center filters cannot be configured to forward to e-mail addresses.
  • Companies cannot be created with a Service Account.
  • Endpoints related to MyUser are not available via Service Accounts (MyUserEmailAddressChangeList, MyUserOtpAuthEnable, MyUserOtpAuthSmsEnable, MyUserPassword) .
  • Scheduled Reports endpoints: QueueReportList.

• No web or app access: Service Accounts cannot be used to log into the IXON Cloud web interface or into the mobile app.

• A Service Account access token cannot be used to for login integrations.

• No email-based features: anything that delivers to a mailbox, such as Scheduled Reports and Email Notifications, is unavailable.

How to create a Service Account

1. Navigate to Admin > Integrations > Service Accounts, click Create Service Account and enter the name of the integration.

2. A dialog shows the Application ID for the Service Account and its Access Token. These are the two credentials your integration needs to perform API calls.

   ❗️

   Save the token now!

   The token must be stored safely immediately, as it will not appear again.

   

3. (Optional) Open the Service Account in the User view to manage its role, the devices it can reach, and its managed users. The default is Administrator.

   📘

   This role applies to the Service Account access token only!

   The role handles calls made with this Service Account's own access token. It does not apply to user access tokens requested with this Application ID — instead, in that scenario, the credentials of the person who signed in handle permissions.

Example

The Application ID goes in the Api-Application header, and the access token in the Authorization header, prefixed with Bearer. Here they are on a real call — AgentList, which returns the agents in a company:

curl --request GET \
     --url 'https://portal.ixon.cloud/api/agents' \
     --header 'Api-Version: 2' \
     --header 'Api-Application: 7NWcb4adPRTK' \
     --header 'Api-Company: <your company publicId>' \
     --header 'Authorization: Bearer Z6XevvDES13tQ2Ti3nDVBJyWS0kRw5D1'

A successful response lists the agents the Service Account's role gives it access to:

{
    "status": "success",
    "type": "AgentList",
    "data": [
        {
            "publicId": "$agentPublicId",
            "name": "$agentName"
        }
    ]
}

The same two headers work on every endpoint; only the URL changes. For Api-Version, Api-Company and the other headers every call needs, see IXON API prerequisites.

What should I do if I lose my Access Token?

There's no way to retrieve it.

For a matter of safety, it is recommended to delete the Service Account whose access token was lost and create a new one, replacing both the application ID and the access token in your integration.