What is an API Key?

An API Key is a unique code that can be used to confirm the identity of a user requesting access to the Telematics Guru API. This is distinct from the Bearer Token which is generated when using Basic Authentication (username and password) to identify a user.

Why Use an API Key?

API Keys are useful for external programs that do not have the ability to dynamically check and refresh a bearer token which expires every 24 hours. This might be because an external system only has a single field in which to insert authentication information, or because it is simply more convenient when using the system ad-hoc to enter a single enduring key.

Who Can Make an API Key?

Users in an organisation with the API Keys functionality that possess the permission API key Manage are able to make an API key for themselves. Users with the API key Manage permission and User Manage can give the permission to others.

What are the Steps to Make an API Key?

1. Ensure that you have API key Manage and your chosen Org has the API Keys functionality enabled.
    
2. Navigate to Account → Manage Account (top right-hand corner)
    
3. Under the Access tab, click generate on your chosen API Key field (1 or 2)
    
4. Copy the API Key and insert it into your external system in a safe manner.
    
5. If you wish, you may choose to use the Store checkbox so that you can keep that specific key on the Manage Account page to copy it again in the future. Doing so is not best practice, but is more convenient than storing the key elsewhere or only in your chosen application. If you choose not to "Store API key" the value in the field will appear as “hidden” on your next visit to this page and you will not be able to copy the key.

FAQ

Why are there two keys? 

The best practice when managing an API Key is to 'rotate' it at least once every 6 months. This means briefly having two keys active, and migrating applications over to the second key before deleting the first key. Having two keys allows you to manually manage this process. 

How long does the key last?

There is no automatic termination of a Telematics Guru API Key. They last until you replace them.

How can I tell which of my users has an API key active?

There is no report that can reveal this information. The best approach is to strictly limit which users get the API Key Manage permission.