Refresh Token

The Refresh Token flow is used by partner applications to obtain access tokens for merchants who have installed their application. This flow uses a refresh token that was delivered via webhook when the installation was created.

📖
Specification: RFC 6749 Section 6

Prerequisites

First of all an application needs to be created which merchants can install. This needs to be an application with type ThirdParty or Native. Native applications may only be created in cooperation with Buckaroo and are intended for more tightly integrated services.

Once the application exists, a webhook subscription must be added for the INSTALLATION.CREATE (and most likely also INSTALLATION.UPDATE) events. This webhook will deliver the refresh token, and also a short-lived access token for ease of access upon the first installation of a merchant. Make sure that the refresh token is stored securely and reliably as there is no way to get it other than this webhook. The delivery will be attempted at most 10 times like all webhooks.

Obtaining Access Tokens

Request Format

Endpoint: POST /oauth/token

Headers:

Authorization: Basic <base64(clientId:clientSecret)>
Content-Type: application/x-www-form-urlencoded

Body Parameters:

Parameter	Type	Required	Description
`grant_type`	string	Yes	Must be `refresh_token`
`refresh_token`	string	Yes	The refresh token from the installation

Note The client id and secret must belong to the installed application of this refresh token.

Successful Response

HTTP Status: 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Response Fields:

Field	Type	Description
`access_token`	string	The JWT access token to use for API authentication. This will have access to all of the scopes that the installation has granted access for.
`token_type`	string	The token type (always `Bearer`)
`expires_in`	number	Token validity period in seconds