​
Overview

Nomba uses OAuth 2.0 to secure API access. You’ll use your client_id and client_secret to obtain an access_token. To get the client credentials from the Nomba dashboard, follow the steps on how to obtain API keys. The authentication flow has three key steps:
  1. Obtain an access_token and refresh_token
  2. Refresh the token when it expires
  3. Revoke the token when no longer needed

​
Obtain Access Token

Use the client_credentials grant to request an access_token and refresh_token. The access_token is required for making API requests. 
    curl --request POST \
      --url https://api.nomba.com/v1/auth/token/issue \
      --header 'Content-Type: application/json' \
      --header 'accountId: <accountid>' \
      --data '{
      "grant_type": "client_credentials",
      "client_id": "replace-with-your-client-id",
      "client_secret": "replace-with-your-client-secret"
    }'

​
Refresh Access Token

Access tokens expire after 30 minutes. Instead of requesting a new token with your credentials, exchange the refresh_token for a new access_token. This avoids exposing your client_secret repeatedly and keeps the process secure.
We recommend refreshing your access_token at least 5 minutes before it expires.
  curl --request POST \
    --url https://api.nomba.com/v1/auth/token/refresh \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --header 'accountId: <accountid>' \
    --data '{
    "grant_type": "refresh_token",
    "refresh_token": "01h4gdx2tctxfjgacbdwrcvs5d1688473602892"
  }'

​
Revoke Access Token

Revoke an access_token when you need to immediately terminate access. This is useful if the token is compromised, expired, or no longer needed. Once revoked, the token is invalid and cannot be used to access resources. 
  curl --request POST \
    --url https://api.nomba.com/v1/auth/token/revoke \
    --header 'Content-Type: application/json' \
    --header 'accountId: <accountid>' \
    --data '{
    "clientId": "2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d",
    "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJHOjhmYWM4M2FjLTc2YjAtNDM1Zi1hYTM1LThkOTU3ZGQ5MjdkZCI6Ikc6OGZhYzgzYWMtNzZiMC00MzVmLWFhMzUtOGQ5NTdkZDkyN2RkIiwiUjpURUFNU19PV05FUiI6IlI6VEVBTVNfT1dORVIiLCJFbWFpbDp2aWN0b3JzaG9hZ2FAZ21haWwuY29tIjoiRW1haWw6dmljdG9yc2hvYWdhQGdtYWlsLmNvbSIsImlhdCI6MTY4MTkxODU3OSwic3ViIjoiNWUyNmNmYjAtNTI5Zi00MTdiLWI4ZDItYWJjNDcxZjRjOWRiIiwiZXhwIjoxNjgxOTIyMTc5fQ.    lQOsyhR1gajKdzE9IHQEtxhQyUrArctEDZiP9pWVTFY"
  }'

​
Authentication Best Practices

To keep your integration secure, follow these best practices:
  • Never expose credentials (client_id, client_secret, refresh_token) in frontend code or public repositories.
  • Use secure storage for tokens in your backend (e.g., environment variables, encrypted storage).
  • Refresh tokens proactively (5 minutes before expiry) instead of waiting until the last moment.
  • Revoke tokens immediately if you suspect they’ve been leaked or compromised.
  • Rotate credentials periodically and remove unused API keys.