Authentication

Authorization: Bearer <access_token>

​

How to obtain credentials

​

Token endpoint

​

API key login

• Content-Type: application/x-www-form-urlencoded
• Body field: apiKey (string)

​

Successful token response

​

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 /v2/api/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

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.

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/v2/api/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;
}

import os
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/v2/api/authentication/token/api-key',
        data={'apiKey': os.environ['TELEMAX_API_KEY']},
        timeout=30,
    )
    r.raise_for_status()
    data = r.json()
    _token = data['access_token']
    _token_expires_at = time.time() + data['expires_in']
    return _token

​

Token scoping

• the token’s company, and
• its direct child companies, unless a child is cancelled.

​

API key rotation

1. Create the new key in the Telemax dashboard (API Keys V2 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).

​

Code examples

curl -s -X POST "https://api.telemax.com.au/v2/api/authentication/token/api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "apiKey=EXAMPLE-api-key-do-not-use-0123456789abcdEF"

const tokenRes = await fetch('https://api.telemax.com.au/v2/api/authentication/token/api-key', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({ apiKey: 'EXAMPLE-api-key-do-not-use-0123456789abcdEF' }),
});
const { access_token, expires_in } = await tokenRes.json();

import requests
r = requests.post(
    'https://api.telemax.com.au/v2/api/authentication/token/api-key',
    data={'apiKey': 'EXAMPLE-api-key-do-not-use-0123456789abcdEF'},
    timeout=30,
)
r.raise_for_status()
token = r.json()['access_token']