OAuth 2.0 authentication

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 and Set up authentication.

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:

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.

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.

{
  "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:

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.

Reuse your cached token while it has at least one minute of validity remaining.
When the remaining validity is less than one minute, request another token.
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

400 Bad Request

{
  "responseCode": "BAD_REQUEST",
  "responseMessage": "The request was invalid."
}

401 Unauthorized

{
  "responseCode": "UNAUTHORIZED",
  "responseMessage": "The credentials provided were not valid."
}

500 Internal Server Error

{
  "responseCode": "INTERNAL_ERROR",
  "responseMessage": "An unexpected error occured, please try again later."
}

Test in Sandbox

Obtain Sandbox credentials through your DVM integration setup.
Request a token from the Sandbox OAuth 2.0 endpoint.
Confirm that the response contains a Bearer token and expires_in.
Call an API operation enabled for your integration with Authorization: Bearer <ACCESS_TOKEN>.
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 for its integration. For broader API environment and integration conventions, see Working with DVM APIs. For human access to DVM applications, see Set up authentication.

DVM APIs

Products

Offers

Consumer Offers

Entitlements

Notifications

Eligibility

Charge

Testing

Before you start

Token endpoints

Request an access token

Handle the token response

Use the token with DVM APIs

Cache and renew tokens

Handle token errors

Test in Sandbox

​Before you start

​Token endpoints

​Request an access token

​Handle the token response

​Use the token with DVM APIs

​Cache and renew tokens

​Handle token errors

​Test in Sandbox

Before you start

Token endpoints

Request an access token

Handle the token response

Use the token with DVM APIs

Cache and renew tokens

Handle token errors

Test in Sandbox