API authentication
Learn how to generate access tokens to authenticate to the Indirect Tax API and manage token expiration.
The Indirect Tax API uses OAuth for authentication. Successful authentication provides an access token that serves as the authentication header in every other API request — except for the Status endpoint, which only requires the API key.
To generate the access token, it's necessary to call the Authorization endpoint using the API Key and the Secret generated for the app. If they are already available, they can be found in the My Apps section of the Developer Hub.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub or client-side code.
After copying the Key and the Secret, you can use an application like Postman, which allows entering these data and getting the access token. Alternatively, they can use cURL. In this case, it's necessary to combine them with a colon (":") in between them. Then, encode this combination in Base64. For example, if the API Key is "Key" and the Secret is "Secret," the encoded header in the request would look like this: QVBJa2V5OlNlY3JldGtleQ==.
Use the access token in the authorization header of the API requests that require it. There is no limit to the number of requests per access token, but access tokens expire after one hour, so you must request a new one before the old one expires. Because new tokens don't overwrite old ones, Sovos recommends generating up to two tokens per hour: one to start working with the API, and another just before the first token expires. In addition, Sovos recommends caching the token on the client side once it is generated and reusing for the duration of its validity.
For countries or functionalities that require TLS authentication, it's necessary to use the TLS-based URL: api-test-tls.sovos.com.
Authentication Endpoints
The Authentication endpoints provide an access token that serves as the authentication header in most API requests.
Available endpoints in the Authentications resource:
| HTTP Method | Endpoint | Description | Status |
|---|---|---|---|
| POST | /oauth/token | Requests an access token that serves as the authorization header in most Indirect Tax API endpoints. | Recommended |
| POST | /oauth/client_credential/accesstoken | Requests an access token that serves as the authorization header in most Indirect Tax API endpoints. | Deprecated |
Sovos advises developers to use the /oauth/token endpoint, which follows the OAuth 2.0 Authorization Framework. While the deprecated endpoint remains functional, it's no longer actively developed, updated, or supported.
POST /oauth/token
| Request body parameter | Type | # | Description |
|---|---|---|---|
grant_type | string | 1..1 | Enter "client_credentials". |
The request body payload must use the x-www-form-urlencoded format.
Request sample
curl --location --request POST 'https://api-test.sovos.com/oauth/token' \
--header 'Authorization: Basic QVBJa2V5OlNlY3JldGtleQ==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'Response sample
{
"refresh_token_expires_in": "0",
"api_product_list": "[Sovos e-Invoicing, Sovos e-Archiving, Sovos Reporting]",
"api_product_list_json": [
"Sovos e-Invoicing",
"Sovos e-Archiving",
"Sovos Reporting"
],
"organization_name": "sovos",
"developer.email": "64742-2ab2-4h56-ba05-7f9a4426bed7@devteam.apigee.io",
"token_type": "Bearer",
"issued_at": "1600775482546",
"client_id": "Ibw...vUT",
"access_token": "t9Pdc4gKoj",
"application_name": "08da4179-f23c-479b-81f0-b7f1a2c58e63",
"scope": "",
"expires_in": "3599",
"refresh_count": "0",
"status": "approved"
}POST /oauth/client_credential/accesstoken
| Query parameter | Type | # | Description |
|---|---|---|---|
grant_type | string | 1..1 | Enter "client_credentials". |
Request sample
curl --location --request POST 'https://api-test.sovos.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
--header 'Authorization: Basic QVBJa2V5OlNlY3JldGtleQ=='Response sample
{
"refresh_token_expires_in": "0",
"api_product_list": "[Sovos e-Invoicing, Sovos e-Archiving, Sovos Reporting]",
"api_product_list_json": [
"Sovos e-Invoicing",
"Sovos e-Archiving",
"Sovos Reporting"
],
"organization_name": "sovos",
"developer.email": "64742-2ab2-4h56-ba05-7f9a4426bed7@devteam.apigee.io",
"token_type": "Bearer",
"issued_at": "1600775482546",
"client_id": "Ibw...vUT",
"access_token": "t9Pdc4gKoj",
"application_name": "08da4179-f23c-479b-81f0-b7f1a2c58e63",
"scope": "",
"expires_in": "3599",
"refresh_count": "0",
"status": "approved"
}