Client Credentials Grant

The client credentials grant is the simplest OAuth grant GoTab supports and is suitable for server-to-server actions, for example, a job that imports GoTab catalog data periodically.

🚧

Warning

This flow is not suitable for front-end only web applications as it would potentially expose your client secret and allow anyone to make api requests using your credentials

Requesting an Access Token

To get an access token you will make a request to the OAuth endpoint with the following request body:

• api_access_id (required)
• api_access_secret (required)
• response_type (optional) - Should be set to token or omitted entirely

The response will be a JSON object with a token and refreshToken as well as information about the expiration date of the token.

curl --request POST \
     --url https://gotab.io/api/oauth/token \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "api_access_id": "string",
     "api_access_secret": "string"
}
'

{
    "tokenType": "Bearer",
    "token": "",
    "initiated": 1659020513,
    "expires": 1659106913,
    "expiresIn": 86400,
    "refreshToken": ""
}

The token is short lived and will expire after 24 hours. It is recommended to refresh your token before 24 hours has elapsed to avoid disruptions.

The refresh token itself does not expire but you will be required to generate a new auth and refresh token if they are revoked so make sure to properly account for that situation.

📘

Refresh Token Errors

An auth token may be revoked at any time so it is also recommended to gracefully handle token expiration errors.

• When a token is expired or has been revoked a 401 error is returned and the request can be retried.
• When a token is invalid a 403 error is returned and you should not retry the request without modifying the data.

Getting access to a location's data

Before making any requests your credentials must be given permission to interact with the resources at one or more locations by an authorized GoTab user.

This can be done by GoTab upon request but you may also choose to provide an OAuth flow for authorized users to do so as part of an automated integration setup process.

This flow consists of two parts

• Construct a button or link on your website or allow GoTab to display an authentication button on GoTab's website that will take users to the authorization portal
• Handle the authorization response in your redirect url

The authorization endpoint is constructed using the base authorization endpoint url and the following query parameters

• api_access_id (required)
• redirect_url (required) - The redirect url for this authorization. Must match exactly one of the redirect urls configured on the integration dashboard.
• response_type (optional) - Must be set to token or omitted entirely for the client credentials flow
• loc_limit (optional) - Specify this if you want to limit the number of locations a user can select at one time. When omitted no limit is applied. Must be greater than 0 for the client credentials flow.

The final endpoint that a user will be directed to may take this form

https://gotab.io/manager/oauth?access_id=<your_access_id>&loc_limit=[number]&redirect_url=<your_redirect_url>

Once the user hits "Authorize" your integration is instantly given access to the permissions the location has selected.

The user's browser will also be redirected to the redirect url. The redirect url will receive the following query params:

• locationUuids - A comma separated list of locations that were just authorized.

You should now be able to access data from all the locations your integration has been approved to use. For example, List locations will return a list of all the locations your integration has access to.