Managing and Refreshing OneMap Token Validity in NodeJS

The OneMap API requires a valid access token for each API request, and tokens need to be refreshed every 72 hours. This tutorial will guide you through the steps to properly authenticate and handle API requests in NodeJS. However the general principle and algorithm applied in this guide is also applicable to other platforms and programming languages.

The tutorial below is based on snippet built on Next.JS with a react frontend framework. We setup a middleware proxy which will take care of calling OneMap API and refreshing the token in a single location.

1. Prerequisites

Before you start, ensure you have the following:

A registered account for the OneMap API.
Your email and password to generate tokens.
A development environment with Node.js and npm/yarn installed.
axios and https libraries installed in your project.

2. Setting Up Environment Variables

Store sensitive information, such as your email, password, and API base URL, in environment variables for security:

ONEMAP_API_EMAIL=your_email@example.com
ONEMAP_API_PASSWORD=your_password
ONEMAP_BASE_URL=https://www.onemap.gov.sg

3. Token Management

To call the OneMap API, a valid token is required. Here's how to manage token retrieval and caching:

Retrieving the Access Token

The getAccessToken function authenticates with OneMap and retrieves an access token:

        const getAccessToken = async () => {
            try {
                const response = await axios.post(
                `${process.env.ONEMAP_BASE_URL}/api/auth/post/getToken`,
                {
                    email: process.env.ONEMAP_API_EMAIL,
                    password: process.env.ONEMAP_API_PASSWORD,
                }
                );

                const accessToken = response.data.access_token;
                setAccessToken(accessToken); // Cache the token for reuse
                return accessToken;
            } catch (error) {
                console.error("Error refreshing token:", error);
                throw new Error("Unable to refresh token");
            }
        };

Storing Tokens in Memory

In order to improve API speed and avoid overloading OneMap API which might result in rate limited ban, you can use a utility like tokenCache to store the token temporarily for reuse without additional API calls.

        // Example utility functions
        let inMemoryToken = null;

        export const setAccessToken = (token) => {
        inMemoryToken = token;
        };

        export const getInMemoryAccessToken = () => inMemoryToken;
    

4. Making The API Calls

You may put the code below under src/pages/api/om/[...externalUrl].js and call all OneMap API via this proxy. Wrap your API call logic in a handler to manage requests and handle token expiry:

Handling API Requests

This handler proxies API requests and refreshes tokens when needed:

        import axios from "axios";
        import https from "https";

        export default async function handler(req, res) {
        const { method } = req;
        const targetUrl = `${process.env.ONEMAP_BASE_URL}/${req.query.externalUrl}`;
        let access_token = getInMemoryAccessToken();

        try {
            const response = await axios({
            method,
            url: targetUrl,
            headers: {
                Authorization: `Bearer ${access_token}`,
                "Content-Type": "application/json",
            },
            params: req.query,
            });

            res.status(response.status).json(response.data);
        } catch (error) {
            if (error.response?.status === 401) {
            try {
                access_token = await getAccessToken();
                const retryResponse = await axios({
                method,
                url: targetUrl,
                headers: {
                    Authorization: `Bearer ${access_token}`,
                    "Content-Type": "application/json",
                },
                params: req.query,
                });

                res.status(retryResponse.status).json(retryResponse.data);
            } catch (retryError) {
                res.status(retryError.response?.status || 500).json({
                message: retryError.message,
                details: retryError.response?.data,
                });
            }
            } else {
            res.status(error.response?.status || 500).json({
                message: error.message,
                details: error.response?.data,
            });
            }
        }
        }
    

The code above acts as a proxy for API calls to OneMap, handling token-based authentication with retry logic.

Primary Request:
- Sends the request to the API with:
  - URL, HTTP method, headers (Bearer token), query params, and HTTPS agent.
- On success, returns the response to the client.
Error Handling:
- 401 Errors: It means the token might be expired. Refreshes the token and retries the request.
- Other Errors: Returns error details (status, message, and response data).

Tips: If you have issue with self signed certificate in development environment, you can consider setting the httpsAgent. However this is NOT recommended in production environment.
const httpsAgent = new https.Agent({ rejectUnauthorized: false });

5. Recommended Practices

Secure Sensitive Data: Always store credentials and tokens securely using environment variables or secure storage solutions.
Efficient Token Use: Avoid repeated calls to /getToken to prevent rate-limiting bans.
Graceful Token Refresh: Automatically renew tokens to ensure uninterrupted API usage.
SSL Validation: Use rejectUnauthorized: false only in development, never in production.

Developer can contact us if you have any questions regarding OneMap API.