OAuth 2.0: Refresh token grant flow

The Refresh Token grant type is used by clients to exchange a refresh token for an access token when the access token has expired. You can get refresh tokens only for the OAuth 2.0: Authorization code flow.

New OAuth2 access tokens have expirations. Tokens return an expires_in field indicating how long the token will last.

A refresh token is a special kind of token that contains the information required to obtain a new access token or ID token. Usually, you will need a new access token only after the previous one expires.

Client requests a new token

The refresh token grant allows your app to ask apaleo to issue a new access_token directly, without re-authenticating the user. This will work as long as the refresh token has not been revoked.

Refresh tokens are subject to strict storage requirements to ensure that they are not leaked.

To refresh your token, using the refresh_token you already got during authorization, make a POST request to the https://identity.apaleo.com/connect/token endpoint in the authentication API, using grant_type=refresh_token.

POST https://identity.apaleo.com/connect/token
Content-Type: application/x-www-form-urlencoded
Request Value
Method POST
URL Uses the OAuth endpoint https://identity.apaleo.com/connect/token.
Header Value
Authorization Basic authorization, using the client id and client secret of the OAuth client.
Content-Type application/x-www-form-urlencoded

Example cURL request

You can test the creation of token by running the following cURL command.

On Windows, use Windows Subsystem for Linux (WSL) to run the cURL command.

curl -X POST \
  https://identity.apaleo.com/connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data  client_id=SDXE-AC-MYAPP \
  --data  client_secret=ZiEWFgFeSP......5yhTgsZgx \
  --data  grant_type=refresh_token \
  --data  refresh_token=E042F......5EC95
Key Description
client_id The ID assigned to your app when it was registered.
client_secret Your client application’s secret.
grant_type The value refresh_token.
refresh_token The refresh_token that you already got when you exchanged authorization code for token in the OAuth 2.0: Authorization code flow.

Authorization server grants a new token

After verifying the request, the identity server sends a response with a new access token to the connected app.

The response will include a new access_token, its type, its lifetime (in seconds), and the id_token.

  "id_token": "eyJ...b9w",
  "access_token": "eyJ...Vsg",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "E042F......5EC95",
  "scope": "openid profile availability.read rates.read reservations.read identity:account-users.read offline_access"

You should only ask for a new token if the access_token has expired, or you want to refresh the claims contained in the id_token. Calling the endpoint to get a new access_token every time you call an API works, but we wouldn’t call it the best practice.

During implementation or debugging, you might want to check the contents of those token, for example, to read the account code. Here’s one handy tool jwt.io. They write “[…] We do not record tokens, all validation and debugging is done on the client side”, and it should be okay to use them, but - better safe than sorry. We recommend to be cautious, and not post the production tokens of real customers there.