Access Iris APIs (API users & access tokens)

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.

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 under Administration → API Access.

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

Attach a name and description to the API User for easy identification.

Capture the username and password of created user along with the "Client ID" and "Client Secret".

📘

Password

Remember to save the password. The password will only be visible this one time.

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'

🚧

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.