Connector API authentication
Less than to read
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 2-factor authentication.
Or, you can let the user enter a 1-time code generated from your solution. This will allow the user to link their account without feeling like they’re entering their banking credentials in another product.
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.
✅ 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.
- 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.
- 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 recieving a request to /auth, the Banking Service will POST to your notification 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 parameters 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 20 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.