Learn how to get and use an access token
Each call to the REST API requires a valid access token.
Use the following steps to obtain an access token.
NOTE: One access token can be used numerous times within its lifetime. Refer to Using an Access Token for more details.
Submit a request to the URL in the token endpoint https://auth.vertexsmb.com/identity/connect/token
using an HTTP POST. Provide the following parameters in the request 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 |
username |
The API key from Vertex Cloud for the client on whose behalf the calls will be made | String, required |
password |
The API password from Vertex Cloud for the client on whose behalf the calls will be made | String, required |
scope (Address Cleansing and Tax Calculation APIs) |
The string calc-rest-api | String, required |
scope (Adjustment File API) |
The string vtms-public-api openid profile | String, required |
grant_type |
The string password | String, required |
The 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.
The username
and password
parameters identify the Vertex Cloud account. These values must be provided to the integration and can vary if there are multiple installations of the integration or if the integration is used for multiple Vertex Cloud accounts.
The response from the call to the token endpoint is a JSON object.
If the call is successful (HTTP status code = 200), the JSON object has multiple properties. For example:
{ "access_token": "valid_token_ID", "token_type": "Bearer", "expires_in": 1200 }
The access_token
and token_type
parameters are needed to make calls against the Vertex REST API. The expires_in
parameter defines the number of seconds until the access token expires. After this time, a new token must be requested.
If an error occurs (HTTP status code != 200), the JSON object has one “error” property with a message that describes the reason for failure. For example:
{ "error" : "invalid_client" }
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.
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.