API authentication
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.
For countries or functionalities that require TLS authentication, you need to use the TLS-based URL: api-test-tls.sovos.com.
Access token generation
To generate the access token, you must call the Authorization endpoint using the API key and the secret generated when you create the API app. If they are already available, you can find them in the 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.
You can use an application like Postman or cURL to generate the access token. If you use cURL, you need to combine the key and the secret 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 looks like this: QVBJa2V5OlNlY3JldGtleQ==.
Access token expiration
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 current token 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.
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"
}