GoTo Developer

How to Obtain and Use Refresh Tokens

A valid access token is required to make a successful API call for GoTo products. Access tokens have a lifespan of 60 minutes. Getting a new access token requires a new login and new token request, or - more easily - a request that contains a refresh token. Refresh tokens are good for longer periods.

To use a refresh token, you send an API token request with a grant type of refresh_token with the refresh token value from the original token request. A sample request is shown below in cURL format.

NOTE: The refresh_token displayed in the examples on this page are truncated. The tokens are significantly larger.

curl --request POST '' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic YTIwfAKeNGYtODY4YS00MzM5LTkzNGYtNGRhMmQ3ODhkMGFhOjNuYU8xMElBMmFnY3ZHKzlJOVRHRVE9PQ==' \
-d 'grant_type=refresh_token&refresh_token=eyJraWQiOiJvYXV0aHYyLmxt999...'

The Authorization header value is the same as the one you used to obtain the original token, namely the string of clientID:clientSecret base64 encoded. The refresh token is the value received in the results body when you received the original access token.

Response example

IMPORTANT: The access token and refresh token values are truncated. They are large values.

  "access_token": "eyJraWQiOiJvYXV0aHYyLmxt666...",
  "refresh_token": "eyJraWQiOiJvYXV0aHYyLmxt999...",
  "expires_in": 3600,
  "principal": "",

Response data

The following is sample output.

Parameter Description
access_token OAuth access token
refresh_token OAuth Refresh token
principal Who the token represents
expires_in The number of seconds until the access token expires

This access token can now be used to authorize API requests by setting it in the Authorization header with the following format:

Authorization: Bearer {access_token}

Example of use

Event 1: Generate an access token. The body of the response contains a new valid access token and a refresh token.

Event 2+n: At any time when you need access (within the next 30 days), send a grant type=refresh token request. The body of the response contains the same refresh token as the first request. Best practice is to harvest the refresh token from the response body daily and use it for the next grant type=refresh token request.

Event 3: At some point, on or about day 30 of the refresh token's lifecycle, the response body will contain a new refresh token, good for the next 30 days.