Authorization Code Grant Flow

The authorization code flow is suitable for clients that would like to assume the role of specific GoTab users when interacting with resources. This can be used to, for example, allow the user to select from a list of the locations they manage, create rich web-based applications for a manager,

This flow generally gives you access to the resources the user themselves has access to as opposed to the user needing to grant the integration ownership of the resources.

The steps to implement the authorization code grant are to

• Direct the user to the authorization endpoint from your website
• Use your redirect URL to handle the response
• Get a token and refresh token from the token endpoints
• Begin making API requests

Constructing the authorization endpoint

Typically this flow requires placing a button or link in your application that will direct the user to GoTab's authorization portal, allowing the user to review and authorize the integration request.

The base authorization endpoint can be passed the following query parameters:

• response_type (required) - Must be set to code
• api_access_id (required) - Your api_access_id
• redirect_url (required) - One of the redirect urls configured for your integration on the integration management dashboard. Be sure that this value matches the exact value of one of the redirect urls.
• state (optional) - An arbitrary string generated by you. Can be used to prevent CSRF attacks and provide request validation. A simple method is to generate a uuid for each press of the button.

https://gotab.io/manager/oauth?response_type=code&access_id=<your_access_id>&state=[state]&redirect_url=<your_redirect_url>

Handling the redirect

After the user confirms the authentication request they will be redirected to the provided redirect with the following query parameters:

• code - A unique authorization code that will be exchanged for the token in the next step
• state - The state variable, if any. This will be exactly the same as the one passed in the previous step and you should use it to determine if the request is authentic.

Exchanging the authorization code for a token

After verifying the redirect is acceptable, you will use the authorization endpoint to exchange the code returned in the previous step for an access token and refresh token. The body params you may provide are:

• response_type (required) - Must be set to code
• api_access_id (required)
• api_access_secret (required)
• code (required) - The authorization code from the previous step

If the code is valid then 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.

Make requests

To make requests, provide the access token as a Bearer token in the Authorization header of any request you make.

Because the authorization code grant flow results in a token associated with a specific user all requests will be performed on behalf of the user as opposed to on behalf of the integration itself.

The List locations route, as an example, should now return only the locations the user has access to and not the locations the integration itself has access to.