The base URL for the APIs is https://iris.trackunit.com/

IRIS APIs use the OAuth 2.0 protocol for authentication and authorization. IRIS APIs supports OAuth 2.0's Resource Owner Password Flow.

To begin, obtain OAuth 2.0 client credentials from the Manager application. Then your client application requests an access token from the IRIS Authorization Server, extracts a token from the response, and sends the token to the IRIS API that you want to access.

This page gives an overview of how to use OAuth 2.0's Resource Owner Password Flow.

📘

Access to Classic API

Please note that access to Classic API is different than access to IRIS API. See Access Classic APIs for further details.

Basic Steps

All applications follow a basic pattern when accessing IRIS API using OAuth 2.0. At a high level, you follow four steps:

1. Obtain OAuth 2.0 credentials from the Manager application.

Visit the Manager application to create an API User and obtain OAuth 2.0 credentials such as a username, password, client ID and client secret that are known to both Trackunit and your application.

🚧

Admin user privileges

API Users will act as the admin user. Only the admin user can access the "API Access"-page to create API Users and obtain credentials.

Find the "API Access" page in the upper right corner of the Manager application.

481

Create a new API User by clicking "Create New API User".

1352

Capture the username and password of created user along with the "Client ID" and "Client Secret". Beware the password will only be visible this one time.

1354

2. Obtain an access token from the IRIS Authorization Server.

Before your application can access private data using a IRIS API, it must obtain an access token that grants access to that API. A single access token can grant varying degrees of access to multiple APIs based on subscription package and add-ons.

Authenticate against the IRIS Authorization Server using the OAuth 2.0 credentials from step 1.

curl --location --request POST 'https://auth.trackunit.com/token' \
--header 'Authorization: Basic PDxjbGllbnRfaWQ+Pjo8PGNsaWVudF9zZWNyZXQ+Pg==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<<username>>' \
--data-urlencode 'password=<<password>>' \
--data-urlencode 'scope=api'
Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://auth.trackunit.com/token")
  .header("Authorization", "Basic PDxjbGllbnRfaWQ+Pjo8PGNsaWVudF9zZWNyZXQ+Pg==")
  .header("Content-Type", "application/x-www-form-urlencoded")
  .field("grant_type", "password")
  .field("username", "<<username>>")
  .field("password", "<<password>>")
  .field("scope", "api")
  .asString();
var client = new RestClient("https://auth.trackunit.com/token");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Basic PDxjbGllbnRfaWQ+Pjo8PGNsaWVudF9zZWNyZXQ+Pg==");
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("grant_type", "password");
request.AddParameter("username", "<<username>>");
request.AddParameter("password", "<<password>>");
request.AddParameter("scope", "api");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://auth.trackunit.com/token',
  'headers': {
    'Content-Type': ['application/x-www-form-urlencoded'],
    'Authorization': 'Basic PDxjbGllbnRfaWQ+Pjo8PGNsaWVudF9zZWNyZXQ+Pg=='
  },
  form: {
    'grant_type': 'password',
    'username': '<<username>>',
    'password': '<<password>>',
    'scope': 'api'
  }
};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

🚧

Authorization Header

Applications has to supply client_id and client_secret through basic authentication. Base64 encode CLIENT_ID:CLIENT_SECRET and include it in the 'Authorization' header e.g. 'Authorization: Basic "BASE64 ENCODED CLIENT_ID:CLIENT_SECRET"'

If the user grants at least one permission, the IRIS Authorization Server sends your application an access token. If the user does not grant the permission, the server returns an error.

A granted permission response from IRIS Authorization Server will be returned as:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "<<access_token>>",
    "scope": "api"
}

3. Send the access token to an API.

After an application obtains an access token, it sends the token to a IRIS API in an HTTP Authorization request header.

4. Refresh the access token, if necessary.

Access tokens have limited lifetimes. If your application needs access to a IRIS API beyond the lifetime of a single access token, it can obtain a new token from the IRIS Authorization Server.