The Refresh Token Grant can be used in conjunction with the authorization code grant type. You can use the refresh_token returned by the authorization code grant to request a fresh access token.

This helps to improve security by keeping access tokens short lived, whilst not impacting the user experience by requiring frequent redirects with the authorization code grant.

Obtaining a new access token

1. Exchange the refresh token for an access token

To obtain an access token you need to make a server-side request to POST https://{client}-api.bipsync.com/v1/oauth/token. You will need to include the following parameters in the request body encoded as form data or JSON:

Parameter name	Type	Description
`client_id`	`string`	Required. The client ID assigned to your application.
`grant_type`	`string`	Required. Use `refresh_token` as the value.
`refresh_token`	`string`	Required. The refresh token.
`client_secret`	`string`	Required for confidential clients. The client secret assigned to your application.
`scope`	`string`	Optional. Space separated list of scopes. If this is omitted then the original access token scopes will be used.

If you request additional scopes that the user had not originally consented to, the request will return a 400 error. You will need to go through the authorization code grant flow again to obtain user consent for these new scopes.

2. Handle the token response

If the request is successful you should receive an HTTP 200 status code and a JSON response in the following format:

{
  "token_type": "bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY...",
  "refresh_token": "def50200abf83399817830585462e876ade62cc3d07bc829582d4b4..."
}

Store the new access_token and refresh_token securely. The existing access/refresh tokens will be revoked.

You can use this process to retrieve new access tokens indefinitely, unless the user revokes their consent or you ask for new scopes.

The refresh token is valid for 1 month. If the refresh token expires, you will need to obtain a new access/refresh token pair using the authorization code grant type.