Re-authorisation

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.

Overview

1. Product initiates re-authorisation, calling into Banking Service.
2. Banking Service sends ‘resource created’ notification to provider.
3. Banking Service calls the GET /authrefresh endpoint. When Banking Service calls the /authrefresh endpoint, the customer should get a UI to enable them to re-authorise. This may be in the event of a customer needing consent with the provider.
4. The provider generates UI for authentication.
5. The provider calls PATCH /authorisations on Provider API, passing an empty array.
6. The UI redirects to Banking Service.
7. Banking Service changes state of account to active.

API flow diagram

1. Set an account to require 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:

{
    "data": {
        "principalId": "(consumer_bankAccountId)",
        "bankId": "(_preset_consumer_bankId)",
        "expected": {
            "transactionDetailsCount": 0,
            "accountDetailsCount": 1,
            "transactionCreditSum": 0,
            "transactionDebitSum": 0
        },
        "accountDetails": [
            {
                "bankAccountId": "(consumer_bankAccountId)",
                "status": "authRequired"
            }
        ],
        "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 re-authorisation flow. When a user’s account has lost its credentials to the provider, the product will initiate the re-authorisation by calling GET /indirectauth.

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

{
  "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.

Test Reauthorisation

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.

What’s next?

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