Access Token

Learn how to get and use an access token

You must supply a valid access token each time you interact with a REST API. You need your OAuth credentials and your API credentials to get an access token.

Obtain an Access Token

You must supply a valid access token each time you interact with a REST API. Use the following steps to obtain an access token.

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.

Success Response

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.

Error Response

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"
}

Authorize a Request

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.