API authentication

Request an access token

Authenticate using your Reloadly client_id and client_secret and obtain an access token through the Reloadly OAuth authentication endpoint.

POST https://auth.reloadly.com/oauth/token
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "grant_type": "client_credentials",
  "audience": "https://topups.reloadly.com"
}

Store the access token securely

Store the returned access token securely within your application. Do not expose your access token, client ID, or client secret in client-side applications, logs, public repositories, or other insecure locations.

Track the token expiry

Reloadly access tokens are valid for 60 minutes. Your application should track when the token was issued and when it will expire.

Renew the token before expiry

Request a new access token before the existing token reaches its 60-minute expiry. We recommend including a small safety buffer rather than waiting until the final second before expiration.

Use the new token

Once the new access token has been successfully issued, use it for subsequent Reloadly API requests.

Handle authentication failures

Your integration should include appropriate error handling. If an API request returns an authentication error because the token is no longer valid, your application should obtain a new access token and retry the request where appropriate.

// Renew 5 minutes before the 60-minute expiry
const SAFETY_BUFFER_MS = 5 * 60 * 1000;
let cachedToken = null;
let expiresAt = 0;

async function getAccessToken() {
  if (cachedToken && Date.now() < expiresAt - SAFETY_BUFFER_MS) {
    return cachedToken; // reuse the valid token
  }
  const res = await requestNewToken(); // calls the OAuth endpoint
  cachedToken = res.access_token;
  expiresAt = Date.now() + res.expires_in * 1000;
  return cachedToken;
}

async function callReloadly(request) {
  let res = await send(request, await getAccessToken());
  if (res.status === 401) {
    cachedToken = null; // force renewal, then retry once
    res = await send(request, await getAccessToken());
  }
  return res;
}