Avinode OAuth 2.0 Token Management

Prerequisites

OAuth must be enabled for your company account. If OAuth is not active, contact [email protected].

To manage OAuth credentials, your Avinode user account must have the following permissions:

Company APIs
Technical Staff

Retrieve OAuth Credentials

Log in to your Avinode Marketplace account: https://marketplace.avinode.com/
Navigate to Company -> APIs -> [Your Connection].
Under OAuth, copy the Client ID.
Generate a Client Secret by clicking New Secret.
Choose one of the available authentication methods:
- client_secret_basic
- client_secret_post
- client_secret_jwt
Select an expiry period for the secret.

Important: Store the client secret securely. It is displayed only once and cannot be recovered later.

Authentication Methods

The token request format depends on the authentication method selected when the client secret was created.

Authentication method	How credentials are sent
`client_secret_basic`	The client credentials are sent in the `Authorization: Basic` header.
`client_secret_post`	The `client_id` and `client_secret` are sent in the form-encoded request body.
`client_secret_jwt`	A signed client assertion JWT is sent in the form-encoded request body.

Use only the authentication method configured for your OAuth credentials. For example, if you selected client_secret_basic, do not also send client_secret in the request body.

Request an Access Token

Endpoint

POST /api/oauth/token

Headers

Accept: application/json
Content-Type: application/x-www-form-urlencoded

Common Body Parameters

Parameter	Description	Required
`grant_type`	Must be `client_credentials`.	Yes
`expiresInMinutes`	Optional token lifetime in minutes. Valid range: 1–120. Defaults to 30 if omitted.	No

Additional parameters depend on the selected authentication method.

Example Request: `client_secret_post`

Use this format when your OAuth credentials are configured for client_secret_post.

Body Parameters

Parameter	Description	Required
`grant_type`	Must be `client_credentials`.	Yes
`client_id`	Your OAuth Client ID.	Yes
`client_secret`	Your OAuth Client Secret.	Yes
`expiresInMinutes`	Optional token lifetime in minutes. Valid range: 1–120. Defaults to 30 if omitted.	No

Request

curl -X POST "https://sandbox.avinode.com/api/oauth/token" \
  -H "Accept: application/json" \
  -H "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" \
  --data-urlencode "expiresInMinutes=30"

Example Request: `client_secret_basic`

Use this format when your OAuth credentials are configured for client_secret_basic.

The client_id and client_secret are sent in the Authorization: Basic header as a Base64-encoded value.

Body Parameters

Parameter	Description	Required
`grant_type`	Must be `client_credentials`.	Yes
`expiresInMinutes`	Optional token lifetime in minutes. Valid range: 1–120. Defaults to 30 if omitted.	No

Request

BASIC_AUTH=$(printf "%s:%s" "YOUR_CLIENT_ID" "YOUR_CLIENT_SECRET" | base64 | tr -d '\n')

curl -X POST "https://sandbox.avinode.com/api/oauth/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $BASIC_AUTH" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "expiresInMinutes=30"

Example Request: `client_secret_jwt`

Use this format when your OAuth credentials are configured for client_secret_jwt.

With this method, the client secret is used to sign a client assertion JWT. The signed JWT is then sent to the token endpoint.

Body Parameters

Parameter	Description	Required
`grant_type`	Must be `client_credentials`.	Yes
`client_assertion_type`	Must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.	Yes
`client_assertion`	The signed client assertion JWT.	Yes
`expiresInMinutes`	Optional token lifetime in minutes. Valid range: 1–120. Defaults to 30 if omitted.	No

Request

curl -X POST "https://sandbox.avinode.com/api/oauth/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=YOUR_SIGNED_CLIENT_ASSERTION_JWT" \
  --data-urlencode "expiresInMinutes=30"

Example Response

A successful token request returns a short-lived access token.

{
  "access_token": "$0m3_eX@mp1e_0f+TOk3n...",
  "expires_in": 1799,
  "token_type": "Bearer"
}

Field	Description
`access_token`	The token used to authenticate API requests.
`expires_in`	Token lifetime in seconds.
`token_type`	Token type. This will be `Bearer`.

Using the Access Token

Include the access token in the Authorization header of each API request:

Authorization: Bearer <access_token>

Tokens expire automatically after the expires_in duration returned by the token endpoint. When a token expires, request a new one using the same OAuth credentials.

Refresh tokens are not issued for the Client Credentials flow.

OAuth Workflow Diagram

When using OAuth to authenticate against Avinode APIs, the Avinode Authorization Server issues a short-lived Access Token.

The token represents the client application's authorization to access Avinode's protected API resources. It is obtained by sending a request to the OAuth Token Endpoint, POST /api/oauth/token, using the Client Credentials grant type.

After the token is issued, use it as a Bearer token in the HTTP Authorization header for subsequent API calls.

Troubleshooting

Below are common errors developers may encounter when requesting or using OAuth access tokens.

Token Request Errors

HTTP Status	OAuth Error Code	Description	Resolution
400	—	Missing or incorrect `Content-Type` header, or malformed form body.	Use `Content-Type: application/x-www-form-urlencoded` and verify the request body is form encoded.
401	`invalid_client`	Client credentials are invalid, expired, revoked, or sent using the wrong authentication method.	Verify the `client_id`, `client_secret`, and selected authentication method.
401	`unauthorized_client`	The client is not authorized to use the requested grant type.	Confirm OAuth is enabled for your company and that the client is configured for Client Credentials Grant.
429	—	Too many token requests.	Cache and reuse valid access tokens until they expire.
500	—	Internal server error.	Retry after a delay. If the issue persists, contact support with the timestamp, response status, and response body.

API Request Errors

HTTP Status	OAuth Error Code	Description	Resolution
401	`invalid_token`	The access token is expired, malformed, revoked, or missing.	Request a new token and include it as `Authorization: Bearer <access_token>`.
403	—	The token is valid, but the client does not have access to the requested resource.	Verify that your API connection has access to the required resource.

Additional Implementation Tips

Use HTTPS exclusively
All requests to Avinode OAuth endpoints must use HTTPS. Requests made over HTTP will be rejected. Verify that your integration, load balancers, and proxies do not downgrade requests to HTTP.
Use the correct authentication method
The token request must match the authentication method selected when the client secret was generated. For example, use the Authorization: Basic header for client_secret_basic, and use body parameters for client_secret_post.
Cache tokens during their validity period
To avoid HTTP 429 - Too Many Requests errors, store and reuse each valid access token until it expires. Request a new token only when necessary.
Respect the token lifetime
The optional expiresInMinutes parameter accepts values from 1 to 120 minutes. If omitted, the default token lifetime is 30 minutes.
No refresh tokens are issued
The Client Credentials flow does not issue refresh tokens. When an access token expires, request a new one using your OAuth credentials.
Keep system time synchronized
Ensure your system clock is synchronized and uses UTC. Token expiration checks depend on accurate time.
Rotate credentials regularly
Rotate your client_secret periodically, for example every 90 days, and remove unused OAuth connections.
Revoke tokens or credentials when needed
You can revoke access under Company -> APIs -> [Your API Connection] -> OAuth. Revocation immediately invalidates the affected token or credential and requires your integration to request a new access token before making additional API calls.
Protect sensitive information
Store client credentials securely and never expose them in client-side code, logs, screenshots, or support requests.
Include safe error context when contacting support
When contacting support, include the timestamp, request URL, response status, response body, and a redacted version of the request payload. Never send your full client_secret or access token.

Prerequisites

Retrieve OAuth Credentials

Authentication Methods

Request an Access Token

Endpoint

Headers

Common Body Parameters

Example Request: client_secret_post

Body Parameters

Request

Example Request: client_secret_basic

Body Parameters

Request

Example Request: client_secret_jwt

Body Parameters

Request

Example Response

Using the Access Token

OAuth Workflow Diagram

Troubleshooting

Token Request Errors

API Request Errors

Additional Implementation Tips

Example Request: `client_secret_post`

Example Request: `client_secret_basic`

Example Request: `client_secret_jwt`