Skip to content
Developer home


  Less than to read

A user needs to re-authorise when their original authorisation has expired. Before they can continue to retrieve transactions through the provider, they need to re-authorise. This process is carried out from the consuming product, allowing the user to relink their bank accounts, which are made available through the providing service.

In this guide we will walk through the API calls made to and from Banking Service from your application and consuming product to demonstrate the re-authorisation flow detailed in our Postman collection.

Read our API flow overview before following this walkthrough. This covers any prerequisites and how to use our Postman collections.

API flow diagram

Flow diagram displaying the authorisation flow

1. Set an account to requires authorisation

If the provider has decided that the account needs to re-authorise, they should set the account status to authRequired when sending a POST to the /statements endpoint. The following demonstrates the payload of this request:

POST /statements

Provider API

  "data": {
    "principalId": "0a52818d-1e0c-4e64-848e-4d04f9e914e5",
    "required": null,
    "expected": {},
    "bankId": "string",
    "accountDetails": [
      "bankAccountId": "5b26b598-a880-4e32-8c41-126aa0206857",
      "status": "authRequired",
      "balances": {}
    "transactionDetails": []

2. Initiate an indirect authorisation

The Sage product can identify if the account requires re-authorisation by checking the bankAccount status. If the account status is set as authRequired, the product will initiate the reAuth flow. When a user’s account has lost its credentials to the provider, the product will initiate the re-authorisation by calling GET /indirectauth.

POST /notification

Connector API

Banking Service notifies the provider that a re-authorisation flow has started. It sends a POST request to the provider’s /notification endpoint with the following payload:

    "type": "resourceCreated",
    "resource": {
        "id": "a7d66d27-e9ab-40b4-850a-447a541ca263",
        "type": "authorisation",
        "url": "NA"
    "additionalData": {
      "bankId": "10aaeee6-4691-4443-8198-df39aaa8007c"

GET /authrefresh

Connector API

Banking Service then calls into the provider’s GET /authrefresh endpoint. When Banking Service calls the /authrefresh endpoint, the connector should perform any neccessary tasks to re-authenticate the user. They may ask the user to enter their internet banking credentials and perform multi-factor authentication.

The following query paramters are sent within the auth request:

Query Parameter Description
bankaccount The sage id of the bank that the user of the Sage Banking service has chosen to on-board with.
authorisation_id UUID of the authorisation session within the Sage Banking Service. Following an authorisation this ID is used in conjunction with Patch Auth to inform the Banking Service of authorised accounts. It can be used to optionally validate against the authorisation id received on the web hook notification.
redirect_uri Url to redirect to upon success or failure. The value of the State query parameter should be appended to this when redirecting.
state uuid to be appended to redirect_uri when redirecting.
externalId The providers unique identifier for the bank account.

POST /oauth/token

Sage ID

Using the provider API to complete requests such as PATCH authorisations, requires a Sage ID bearer token and an API key to authenitcate the call.

An API key will be provided to you by the Sage team through the setup proccess. To Generate a Sage ID bearer token you can make a POST request to the token endpoint as detailed below. This token generally lasts 480 minutes but should be refreshed when receiving a 401 Unauthenticated responses from the API.

This request should be sent with the following body:

Body Params Description
grant_type This should be set as client_credentails.
client_id This value identifies your client, and is tied to your provider; only tokens generated with your clientId can access resources associated with your provider.
client_Secret This value is required in order to generate SageId tokens. It should be handled as a secret and not shared.
audience This value identifies the Provider API and ensures that generated SageId tokens are targeted at the correct API.

These resources (keys) will be supplied by the Sage team.

PATCH /authorisations

Provider API

The provider informs Banking Service of the results of the re-authorisation session of this bank account. In the case of a re-authorisation, you will not need to send any data regarding accounts. Banking Service then takes responsibility for determining which account the re-authorisation session is for.

The following is the example of the payload which should be provided:

  "data": {
    "status": "success"

When this Patch has been called, the provider should redirect back to the Banking Service UI. The redirect URI to be used is available as a query paramater within the GET /authrefresh call previously made by the Banking Service UI to the provider.


This walkthrough has looked at the re-authorisation flow. Covering how the provider first sets the account to be flagged as required authorisation and how the consuming Sage product triggers calls to the provider to authorise the user through the Banking Service.

Next steps

Find out about the multi-account linking flow. This allows users to connect multiple accounts from 1 authorisation.