## Prerequisites OAuth must be enabled for your company account. If OAuth is not active, contact [techsupport@avinode.com](mailto:techsupport@avinode.com). To manage OAuth credentials, your Avinode user account must have the following permissions: - **Company APIs** - **Technical Staff** ## Retrieve OAuth Credentials 1. Log in to your Avinode Marketplace account: [https://marketplace.avinode.com/](https://marketplace.avinode.com/) 2. Navigate to **Company -> APIs -> \[Your Connection]**. 3. Under **OAuth**, copy the **Client ID**. 4. Generate a **Client Secret** by clicking **New Secret**. 5. Choose one of the available authentication methods: - `client_secret_basic` - `client_secret_post` - `client_secret_jwt` 6. Select an expiry period for the secret.

**Important:** Store the client secret securely. It is displayed only once and cannot be recovered later. ![](https://files.readme.io/9b8168f1c26dcb6f2c9341703f5eb831fcd10bc8e5ccee5a6b32c54e0c10158d-image.png)
## 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](https://developer.avinodegroup.com/reference/tokenrequest) ### Headers ```curl 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 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 ```curl 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 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. ```json { "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: ```curl Authorization: Bearer ``` 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](https://developer.avinodegroup.com/reference/tokenrequest), 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 `. | | 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 1. **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. 2. **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`. 3. **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. 4. **Respect the token lifetime**
The optional `expiresInMinutes` parameter accepts values from 1 to 120 minutes. If omitted, the default token lifetime is 30 minutes. 5. **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. 6. **Keep system time synchronized**
Ensure your system clock is synchronized and uses UTC. Token expiration checks depend on accurate time. 7. **Rotate credentials regularly**
Rotate your `client_secret` periodically, for example every 90 days, and remove unused OAuth connections. 8. **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. 9. **Protect sensitive information**
Store client credentials securely and never expose them in client-side code, logs, screenshots, or support requests. 10. **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.