Access Token

Learn how to get and use an access token

Each call to the REST API requires a valid access token.

Obtaining an Access Token

By default, you can submit up to 10 access token requests to the standard access token endpoint every 8 hours. Exceeding the rate limit generates an error.

NOTE: One access token can be used numerous times within its lifetime. Refer to Using an Access Token for more details.

To help manage your Vertex RESTful API access tokens and reduce the need for frequent token generation, you can implement token caching using:

  • Local caching with the standard access token endpoint

or

Local caching process

Use the following process to obtain an access token with the standard token endpoint.

Use an HTTP POST to submit a request to the URL in the token endpoint:
https://auth.vertexcloud.com/oauth/token

Provide the following parameters in the request body:

Parameter NameDefinitionType
client_idThe client ID provided by Vertex for the custom integrationString, required
client_secretThe client secret provided by Vertex for the custom integrationString, required
scope (Payroll Tax Calculation Prod)payroll-calculationString, required
scope (Payroll Tax Calculation Test)payroll-calculation-testString, required
scope (Address Cleansing Prod)payroll-addr-cleanseString, required
scope (Address Cleansing Test)payroll-addr-cleanse-testString, required
grant_typeclient_credentialsString, required
audienceverx://migration-apiString, required

The client_id and client_secret parameters are issued for each integration against the REST API. Do not expose these confidential values to any users of the integration.

The response from the call to the token endpoint is a JSON object.

Client_id and client_secret are BASE64 ASCII encoded to Authorization: Basic BASE64{client_id : client_secret}
Request ‘content-type’ is ‘application/x-www-form-urlencoded’ – Ensure the parameters in the message body are FormURLencoded.

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, you must request a new token.

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

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 when a new token is needed.

Do not request a new access token for each REST request - this reduces processing rates and increases processing times. If you do not reuse access tokens properly, you may exceed the authorization request limit.

Authorizing 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.