To access the API you need to have a "Personal Access Token" (PAT). You can create a PAT by logging into the Sensium Connect UI and navigating to the Settings page of your logged in user.

From the Settings page you can create a PAT. Each PAT can be given a name. We strongly recommend that you do not share PATs between API clients. This way if you ever need to revoke a PAT you can do so easily from the Settings page.

login

Your API client should first login by issuing a POST request to the /login endpoint.

e.g.

$ curl -X POST -H"Content-Type: application/json" -d'{"token": "<TOKEN>"}' https://connect.sensium.nz/login
{
   "sid": "abcdef-123456-789012"
}

This request should be a JSON object and include the following parameters:

• token - the personal access token

The response to this request will be a JSON object containing EITHER:

• error - if the provided credentials were not accepted
• sid - the session ID if login was successful

making requests

The returned session id should be provided in all requests to /graphql via an authorization header:

$ curl -X POST -H"Authorization: Bearer abcdef-123456-789012" -dquery='{ me { name } }' https://connect.sensium.nz/graphql
{"data": {"me": {"name": "API User"}}}

logout

A session will persist for up to 30 minutes when not being used. Using the session (by making requests) will extend the session timer. The session can be terminated before timing out by making a POST request to /logout.

$ curl -X POST -H"Authorization: Bearer abcdef-123456-789012" https://connect.sensium.nz/logout

The primary top level query items are:

me

This represents the user that owns the PAT you have logged in with. You can navigate the object tree from here to see the "user" view of the system.

account

This represents the account that the logged in user is a member of. You can navigate the object tree from here to see the "account" view of the system (assuming the logged in user has sufficient permissions on the account).

There are also top level queries for specific objects:

• unit - Access a unit directly by id
• driver - Access a driver directly
• user - Access another user (requires "admin" privelege on the account)
• alert - Access an alert directly
• unitgroup - Access a group directly

There are a couple of additional top level query items:

• brand - Information on the specific brand that this account belongs to (e.g. Sensium Connect NZ)
• candisplayadvice - Provides information on how to output templated CAN data in a human readable form

Automotive CAN data is captured by units using templates designed for specific vehicles (or groups of vehicles). Each template captures potentially different data.

The can data ends up as a simple JSON object where each key refers to a single item of data about the vehicle, e.g. vin for the vehicle identification number.

The can data object includes a key _ whose value is an integer indicating the id of the can template used to collect the data. Information on what keys are collected by this can template and the best way to display them can be accessed via the candisplayadvice top level query.

{
    candisplayadvice(10) {
        keys {
            key label islist units precision
        }
    }
}

This will return "display advice" that lists all the keys that can be present in the data and how to display that data to a human.

CAN data is available on a units point field,

{
    unit(123) {
        point {
            can
        }
    }
}

This would retrieve the current can data for the given unit.