Skip to content
Developerhome

Connector API authentication

  Less than to read

Connector APIBanking Service -> Provider

When Banking Service calls your GET /auth endpoint, you should return the HTML which performs any neccessary tasks to authenticate the user. You may ask the user to enter their internet banking credentials and perform multi-factor authentication.

Alternatively to entering credentials you may instead which to allow the user to enter a 1 time code, which is generated from in your solution. This will allow the user to link their account without the feeling of entering their banking credentials in another product.


GET/auth

Request

The following query parameters are sent in the GET auth request:

Query Parameter Description
bank 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 in 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.

Response

You should respond to this request with the HTML for your authorisation proccess.


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.
  • 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.
  • Effectivley 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, and people with situational disabilities like having a broken wrist, needing stronger reading glasses, or being a new parent with poor concentration levels.

We follow accessibility guidelines to ensure that Sage is 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 recieving a request to /auth, the Banking Service will POST to your notifications endpoint with resource type ‘authorisation’ to advise you that the authorisation flow has started. This request will also contain an AuthorisationID which you can use to secure any requests into /auth.

You can do this by comparing the AuthorisationID recieved through the notification body to the AuthorisationID recieved within the query paramters to /auth. 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 10 minutes and can only be used one time.

This AuthorisationID would then be used when sending your PATCH request to the authorisations endpoint through the Provider API.


Was this helpful?