Authorisation refresh
Less than to read
This endpoint handles re-authorisation flow from the Provider API. When a users account has lost its credentials to the provider.
Banking Service then calls into the provider’s GET /authrefresh endpoint. When Banking Service calls the /authrefresh endpoint, the connector should perform any necessary tasks to re-authenticate the user. You may ask the user to enter their internet banking credentials and perform multi-factor authentication.
Request
The following query parameters are sent within the GET auth request:
| Query Parameter | Description |
|---|---|
bankaccount |
The Sage ID of the bank that the user of the Banking service has chosen to onboard 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 providers unique identifier for the bank account. |
Response
You should respond to this request with the HTML for your re-authorisation process. You can return any valid HTML in the response, and it’ll be embedded in the ‘body’ section of a page. For redirection this HTML can be as small as an immediately executing JS script which sets the window.location = wherever you want to go. For example, <script>window.location = X</script>.
User experience
To ensure our mutual customers have a consistently great experience, all content provided should follow these principals:
- Clear: Content should be unambiguous and jargon-free. It should be easily understood in context.
- Concise: Content should be economical and front-loaded with what’s important.
- Useful: Content should be informative and appropriately guide the user’s next actions.
✅ Recommended
- Allow the customer to easily continue their journey without forcing them to open a new window or tab and have to toggle between screens to progress. We offer iFrame support to help with creating a great experience.
- Effectively communicate messages and navigation when redirecting users between services.
- Information is kept to a minimum to help prevent cognitive overload and allow for easier consumption of key elements, information is more likely to be consumed effectively in several small snippets than a single paragraph.
- Navigation and elements that inform the user where they are in their current journey.
Accessibility standards
Accessibility ensures all our customers feel welcome in our products, websites, and apps and can use them easily. This includes:
- People with different levels of vision and hearing.
- People with motor or cognitive impairments.
- People with situational disabilities like having a broken wrist, needing stronger reading glasses, or being a new parent with distractions to concentration.
We follow accessibility guidelines so that we’re compliant with the law in several jurisdictions, including Canada, the United States, the European Union, and the United Kingdom, which prohibit discrimination based on ability.
We are committed to being fully compliant with WCAG standards, as such we require all services to be compliant to WCAG 2.1 Level AA.
Securing this endpoint
Before receiving a request to /authrefresh, the Banking Service will POST to your notification endpoint with resource type ‘authorisation’ to advise you that the re-authorisation flow has started. This request will also contain an AuthorisationID which you can use to secure any requests into /authrefresh.
You can do this by comparing the AuthorisationID received through the notification body to the AuthorisationID received in the query parameters to /authrefresh. If the authorisation identifier values do not match, the request is not secure and should not be processed.
The lifetime of this authorisation session is around 20 minutes and can only be used 1 time.
This AuthorisationID would then be used when sending your PATCH request to the authorisations endpoint through the Provider API.