> ## Documentation Index
> Fetch the complete documentation index at: https://developer.nomba.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate

> Learn how to ensure secure access to Nomba API Resources.

## 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](/docs/getting-started/get-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.

<CodeGroup>
  ```bash cURL theme={null}
      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"
      }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.nomba.com/v1/auth/token/issue', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'accountId': '<accountid>',
    },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: 'replace-with-your-client-id',
      client_secret: 'replace-with-your-client-secret',
    }),
  });

  const { code, data } = await response.json();
  if (code !== '00') throw new Error('Authentication failed');

  const { access_token, refresh_token, expiresAt } = data;
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.nomba.com/v1/auth/token/issue',
      headers={
          'Content-Type': 'application/json',
          'accountId': '<accountid>',
      },
      json={
          'grant_type': 'client_credentials',
          'client_id': 'replace-with-your-client-id',
          'client_secret': 'replace-with-your-client-secret',
      },
  )

  result = response.json()
  if result['code'] != '00':
      raise Exception('Authentication failed')

  access_token = result['data']['access_token']
  refresh_token = result['data']['refresh_token']
  ```

  ```json Response theme={null}
    {
      "code": "00",
      "description": "Success",
      "data": {
        "businessId": "01a10aeb-d989-460a-bbde-9842f2b4320f",
        "access_token": "eyJhbGciOiJIUzI1NiJ9...",
        "refresh_token": "01h4gdx2tctxfjgacbdwrcvs5d1688473602892",
        "expiresAt": "2022-07-08T14:33:00Z"
      }
    }
  ```
</CodeGroup>

## 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.

<Note>
  We recommend refreshing your `access_token` at least 5 minutes before it expires.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
    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"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.nomba.com/v1/auth/token/refresh', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      'accountId': '<accountid>',
    },
    body: JSON.stringify({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
    }),
  });

  const { code, data } = await response.json();
  if (code !== '00') throw new Error('Token refresh failed');

  const newAccessToken = data.access_token;
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.nomba.com/v1/auth/token/refresh',
      headers={
          'Authorization': f'Bearer {access_token}',
          'Content-Type': 'application/json',
          'accountId': '<accountid>',
      },
      json={
          'grant_type': 'refresh_token',
          'refresh_token': refresh_token,
      },
  )

  result = response.json()
  if result['code'] != '00':
      raise Exception('Token refresh failed')

  new_access_token = result['data']['access_token']
  ```

  ```json Response theme={null}
    {
      "code": "00",
      "description": "Success",
      "data": {
        "businessId": "01a10aeb-d989-460a-bbde-9842f2b4320f",
        "access_token": "eyJhbGciOiJIUzI1NiJ9...",
        "refresh_token": "01h4gdx2tctxfjgacbdwrcvs5d1688473602892",
        "expiresAt": "2022-07-08T14:33:00Z"
      }
    }
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```bash cURL theme={null}
    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": "<access_token_to_revoke>"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.nomba.com/v1/auth/token/revoke', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'accountId': '<accountid>',
    },
    body: JSON.stringify({
      clientId: '2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d',
      access_token: accessToken,
    }),
  });

  const { code } = await response.json();
  if (code !== '00') throw new Error('Token revocation failed');
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.nomba.com/v1/auth/token/revoke',
      headers={
          'Content-Type': 'application/json',
          'accountId': '<accountid>',
      },
      json={
          'clientId': '2242b79d-f2cf-4ccc-ada1-e890bd1a9f0d',
          'access_token': access_token,
      },
  )

  result = response.json()
  if result['code'] != '00':
      raise Exception('Token revocation failed')
  ```

  ```json Response theme={null}
    {
      "code": "00",
      "description": "Token revoked successfully"
    }
  ```
</CodeGroup>

## 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.