Skip to content
Developerhome
Product homepage
Banking Service

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.

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

Flow diagram displaying the authorisation flow

Participant description
  • Product The Sage product which is currently integrated with banking service UI using consumer API.
  • UI The user interface which allows the Sage user to search for a bank and allows them to authenticate.
  • Banking Service Banking Service handles the calls from the consuming API which Sage products use to interact with Banking Service. Also handling the provider API which handles the connection from any 3rd party provider.
  • Sage ID Sage ID is used to secure all requests into the provider API. You will use Sage ID to obtain your access token.
  • Provider This refers to the 3rd party who is integrating with Banking Service. This 3rd party connector will need to contain the connector API endpoints to be able to handle the Banking Service flows and recieve data.

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:

POST /statements

Provider APIProvider -> Banking Service
{
    "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.

POST /notification

Connector APIBanking Service -> Provider

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": {s
      "bankId": "10aaeee6-4691-4443-8198-df39aaa8007c"
    }
}


GET /authrefresh

Connector APIBanking Service -> Provider

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. You may ask the user to enter their internet banking credentials and perform multi-factor authentication.

The following query parameters are sent within the auth request:

Query Parameter Description
bankaccount The Sage ID of the bank that the user of the Banking service has chosen to on-board with.
authorisation_id UUID of the authorisation session within the 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 provider’s unique identifier for the bank account.


POST /oauth/token

Sage IDProvider -> 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 APIProvider -> Banking Service

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.

Test Reauthorisation

Test description Expected outcome
When reauthorisation of an account is required, you need to be able to set the customer’s bank account to authentication required. The bank account status field should be set to ‘authRequired’ which is returned when calling to the GET /bankaccounts endpoint.
A customer needs to be able to reauthorise a single linked account when set to auth required. The bank account status field should change from ‘authRequired’ to ‘verifyingAuth’ which is returned when calling to the GET /bankaccounts endpoint.

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.

Was this helpful?