Skip to content
Developer home

Re-authorisation

  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
bank The Sage ID of the bank that the user of the Sage Banking Service has chosen to onboard 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 webhook 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.

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.


Recap

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.