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

# OAuth 2.0 authentication

> Authenticate inbound DVM API requests with OAuth 2.0 Client Credentials, including token requests, caching, Bearer headers, errors, and Sandbox testing.

Use OAuth 2.0 Client Credentials to authenticate machine-to-machine API requests from your systems to Bango DVM™. Bango provisions your integration credentials. Your systems retrieve access tokens, cache them, and send them with supported API requests.

OAuth 2.0 Client Credentials is the **default and recommended** authentication method for enterprise DVM integrations. Use the authentication method supported by your API and configured for your integration.

## Before you start

* Bango provisions DVM OAuth 2.0 credentials for your integration during the onboarding process.
* Obtain the `client_id` and `client_secret` for the environment you are connecting to.
* Use the token endpoint for the same environment as the DVM API you intend to call.
* Your application is responsible for requesting and managing its access tokens.

For credential provisioning, contact Bango through your onboarding process. See [DVM onboarding](https://docs.bango.com/getting-started/dvm-onboarding.md) and [Set up authentication](https://docs.bango.com/partner-management/setup-authentication.md).

> [!WARNING]
>
> Do not mix Sandbox and Production credentials, tokens, or API endpoints. Keep client secrets and access tokens out of source code, URLs, logs, and client-side applications.

## Token endpoints

| Environment | Token endpoint |
| - | - |
| Sandbox | `https://sandbox.auth.bango.com/oauth2/token` |
| Production | `https://auth.bango.com/oauth2/token` |

## Request an access token

Send an HTTPS `POST` request to the token endpoint with an `application/x-www-form-urlencoded` body containing these fields:

| Field | Value |
| - | - |
| `grant_type` | `client_credentials` |
| `client_id` | The client ID supplied for your integration |
| `client_secret` | The corresponding client secret supplied for your integration |

Example using Sandbox:

```bash theme={null}
curl --request POST \
  'https://sandbox.auth.bango.com/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
  --data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'
```

Use the Production token endpoint and Production credentials for Production.

> [!NOTE]
>
> The values in angle brackets are placeholders, not valid credentials.

## Handle the token response

A successful token request returns HTTP `200 OK` with an access token, token type, and validity period.

```json theme={null}
{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 3599,
  "token_type": "Bearer"
}
```

| Response field | Meaning |
| - | - |
| `access_token` | Token to send in the `Authorization` header |
| `expires_in` | Remaining validity in seconds at the time of the response |
| `token_type` | `Bearer` |

The value `3599` is illustrative, **not a fixed token lifetime**. Use the `expires_in` value in each token response to calculate when that token expires.

## Use the token with DVM APIs

Include the access token in the `Authorization` header of requests to DVM APIs that support OAuth 2.0:

```http theme={null}
Authorization: Bearer <ACCESS_TOKEN>
```

You can use the same OAuth 2.0 access token when calling these DVM API service families, subject to the permissions configured for your integration:

* Entitlements API
* Products and Offers API
* Consumer Offers API
* Billing Public API
* Partner Services Eligibility API

A token does not grant access to every API operation. Your configured integration and API permissions still determine what you can call. Use the endpoint and contract for the relevant API family.

## Cache and renew tokens

Cache the access token rather than requesting one for every DVM API call. Track its remaining lifetime from the `expires_in` value.

1. Reuse your cached token while it has at least one minute of validity remaining.
2. When the remaining validity is less than one minute, request another token.
3. Replace the cached token with the token returned and update its expiry information.

The token service returns the existing access token while it remains valid for at least 60 seconds. When fewer than 60 seconds remain, the service issues a new token. Use the token returned by the service whether it is reused or newly issued; a token request does not necessarily produce a different token.

## Handle token errors

The token endpoint returns the following HTTP errors and response codes:

| HTTP status | `responseCode` | What to check |
| - | - | - |
| `400 Bad Request` | `BAD_REQUEST` | Required fields, form encoding, and `grant_type` |
| `401 Unauthorized` | `UNAUTHORIZED` | Client ID and secret, and the selected environment |
| `500 Internal Server Error` | `INTERNAL_ERROR` | Retry later; contact Bango if the problem persists |

> [accordion] 400 Bad Request
>
> ```json theme={null}
> {
>   "responseCode": "BAD_REQUEST",
>   "responseMessage": "The request was invalid."
> }
> ```

> [accordion] 401 Unauthorized
>
> ```json theme={null}
> {
>   "responseCode": "UNAUTHORIZED",
>   "responseMessage": "The credentials provided were not valid."
> }
> ```

> [accordion] 500 Internal Server Error
>
> ```json theme={null}
> {
>   "responseCode": "INTERNAL_ERROR",
>   "responseMessage": "An unexpected error occured, please try again later."
> }
> ```

## Test in Sandbox

1. Obtain Sandbox credentials through your DVM integration setup.
2. Request a token from the Sandbox OAuth 2.0 endpoint.
3. Confirm that the response contains a Bearer token and `expires_in`.
4. Call an API operation enabled for your integration with `Authorization: Bearer <ACCESS_TOKEN>`.
5. Confirm that your application reuses its cached token and renews it before expiry.

Before moving to Production environment, confirm that your application uses Production credentials and endpoints, handles token errors without exposing credentials, and meets the [testing requirements](https://docs.bango.com/testing/testing-overview.md) for its integration.

For broader API environment and integration conventions, see [Working with DVM APIs](https://docs.bango.com/API/working-with-dvm-apis.md). For human access to DVM applications, see [Set up authentication](https://docs.bango.com/partner-management/setup-authentication.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.