API Authentication and Access
You use an access token to authenticate requests. Before you do, you must ensure that you have the correct user credentials to retrieve the token.
API authentication is a vital part of managing the security of your REST-enabled applications.
Access to the API is granted by adding a valid access token to your requests.
Warning
The token must be kept secret and not revealed to anyone. If a token is compromised, you need to reset it immediately.
Access Token Prerequisites
Before you can retrieve the access token, you need the following:
- Vertex e-Invoicing credentials
- OAuth credentials
Vertex e-Invoicing Credentials
Your account credentials identify you as an authorized Vertex e-Invoicing user. Work with the Vertex Sales team to establish an account that meets your tax needs. Learn More
OAuth Credentials
After you create a Vertex e-Invoicing account, you can log in and generate your own Client ID and Client Secret, which identifies you as an authorized OAuth user.
To learn how to generate a client_id
and client_secret
, see the API credential creation for e-Invoicing and Accessing e-Invoicing topics on Vertex Community.
Access Token
The combination of your Vertex e-Invoicing credentials and your OAuth credentials are used to request an Access Token that allows you to access the REST APIs.
Retrieving an Access Token
Each call to the REST API requires a valid access token.
NOTE: One access token can be used numerous times within its lifetime. Refer to Using an Access Token for more details.
To obtain an access token, send a request using a POST method to the following token endpoint URL:
https://auth.vertexcloud.com/oauth/token
Specify the following parameters in the request's body:
Parameter Name | Definition | Type |
---|---|---|
client_id | The client ID provided by Vertex for the custom integration | String, required |
client_secret | The client secret provided by Vertex for the custom integration | String, required |
audience | The string verx://migration-api | String, required |
grant_type | The string client_credentials | String, required |
A token request should contain all of the above parameters. For example:
{
"client_id": "",
"client_secret": "",
"audience": "verx://migration-api",
"grant_type": "client_credentials"
}
client_id
and client_secret
parameters are issued for each integration against the REST API. They are confidential values and should not be exposed to any users of the integration. To learn how to generate a client_id and client_secret, refer to the Vertex e-Invoicing Getting Started Guide available on the
Vertex Community website.The response from the call to the token endpoint is a JSON object.
Success Response
If an error occurs, the JSON object has one “error” property with a message that describes the reason for failure. For example:
{
"error" : "invalid_client"
}
Using an Access Token
When an access token is successfully retrieved, the returned JSON object has multiple properties. The expires_in
property defines how many seconds after the token is issued that the access token is valid. This token is added to the HTTP header to validate/authorize subsequent REST calls.
Note
Best practices dictate that an access token be used for most of its lifetime.
Use the expires_in
property and the response time of the authorization request to determine if a new token is needed. Requesting a new access token for each REST request is not an acceptable practice because it reduces processing rates and increases processing times. Failure to reuse access tokens properly can cause rate limits on authorization requests to be exceeded.
Authenticating Requests
All API requests against the REST API endpoints must be made over HTTPS. When making a request, set the access token in the ‘Authorization’ header of the request with the token type and access token. For example:
Authorization: Bearer {ACCESS_TOKEN}
Or, using the above response as an example:
Authorization: Bearer "valid_token_ID"
This example is for illustration purposes only. It will not work in the API.
Updated about 1 month ago