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 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 |
scope (Payroll Tax Calculation Prod) | payroll-calculation | String, required |
scope (Payroll Tax Calculation Test) | payroll-calculation-test | String, required |
scope (Address Cleansing Prod) | payroll-addr-cleanse | String, required |
scope (Address Cleansing Test) | payroll-addr-cleanse-test | String, required |
grant_type | client_credentials | String, required |
audience | verx://migration-api | String, 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.
Updated 3 months ago