Skip to main content
The External API uses JWT Bearer tokens (HS256 symmetric signing). All business routes expect: 
Authorization: Bearer <access_token>
There is no API-key-in-header pattern for data routes: you exchange the API key for a JWT using the token endpoint, then call /api/v2/* with the Bearer token.

​
How to obtain credentials

MethodWhen to use
API keyYour company issued a GUID API key in the Telemax dashboard, or a legacy non-GUID key resolved via the legacy tracking service.
Credentials are not passed on every data request—only the JWT.

​
Token endpoint

​
API key login

POST /api/v2/authentication/token/api-key
  • Content-Type: application/x-www-form-urlencoded
  • Body field: apiKey (string)

​
Successful token response

JSON fields (see JwtTokenResponse):
FieldTypeDescription
access_tokenstringJWT for Authorization: Bearer
token_typestringAlways bearer
expires_innumberLifetime in seconds

​
JWT claims

Claim types are the string names of JwtClaims (e.g. UserId, CompanyId, TimeZone). API key logins may also include Vehicles, Actions, and DateFormat for scoped keys.

​
Token expiry and refresh

  • Default token lifetime: ~24 hours (expires_in: 86399 seconds).
  • The actual lifetime may vary if the server’s JWT:TokenExpiryTime setting is configured (minimum 5 minutes).
  • There is no refresh endpoint — when a token expires, re-authenticate using POST /api/v2/authentication/token/api-key.
  • Recommendation: Re-authenticate 5 minutes before the token expires rather than waiting for a 401 response. See Token caching strategy below.

​
Token caching strategy

Do not request a new token on every API call. Each token is valid for ~24 hours. Requesting tokens unnecessarily adds latency and risks hitting future rate limits.
Recommended approach:
  1. On startup, request a token and store it in memory with its expiry time (Date.now() + expires_in * 1000).
  2. Before each API call, check if the token expires within the next 5 minutes.
  3. If yes, re-authenticate and replace the cached token.
  4. If no, use the cached token.
Example (JavaScript): 
let cachedToken = null;
let tokenExpiresAt = 0;

async function getToken() {
  if (cachedToken && Date.now() < tokenExpiresAt - 5 * 60 * 1000) {
    return cachedToken;
  }
  const res = await fetch('https://api.telemax.com.au/api/v2/authentication/token/api-key', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ apiKey: process.env.TELEMAX_API_KEY }),
  });
  const { access_token, expires_in } = await res.json();
  cachedToken = access_token;
  tokenExpiresAt = Date.now() + expires_in * 1000;
  return cachedToken;
}
Example (Python): 
import time
import requests

_token = None
_token_expires_at = 0

def get_token():
    global _token, _token_expires_at
    if _token and time.time() < _token_expires_at - 300:
        return _token
    r = requests.post(
        'https://api.telemax.com.au/api/v2/authentication/token/api-key',
        data={'apiKey': os.environ['TELEMAX_API_KEY']},
    )
    r.raise_for_status()
    data = r.json()
    _token = data['access_token']
    _token_expires_at = time.time() + data['expires_in']
    return _token

​
Token scoping

Every token is bound to a single company. The CompanyId claim in the JWT determines which resources the token can access.

​
API key tokens

API key tokens carry additional optional claims:
ClaimEmpty value meansNon-empty value means
VehiclesAll vehicles in the companyComma-separated list of allowed vehicle IDs
ActionsAll actionsComma-separated list of allowed action strings
DateFormat—User’s configured date format
To check which companies and vehicles your token can access, call GET /api/v2/companies and POST /api/v2/vehicles/list after authenticating.

​
API key rotation

To rotate an API key without downtime:
  1. Create the new key in the Telemax dashboard (Webhooks and API Key section). Both keys are active simultaneously.
  2. Update your integration to use the new key and confirm tokens are being obtained successfully.
  3. Delete the old key in the dashboard. Existing tokens issued with the old key remain valid until they expire (up to 24 hours).
Deleting a key immediately invalidates future token requests with that key. Tokens already issued remain valid until their expires_in elapses.

​
Code examples

curl -s -X POST "https://api.telemax.com.au/api/v2/authentication/token/api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "apiKey=a3f1c2b4-5d6e-7890-abcd-ef1234567890"