Basiq's Consent UI

The Consent UI

The Basiq Consent UI is designed to handle all of the complexity behind CDR legislation, consent management, and CX guidelines, so partners can fast track their access to Open Banking data, and focus on innovation.

The Consent UI is driven by the application's own Consent Policy, which acts as a contract for end users to agree to before proceeding to connect their institutions.

Dynamic switching

The Consent UI focuses on providing a seamless user experience no matter the method of data retrieval. What this means, is that it can be used for both web, and Open Banking, connections. Consent applies to the application/user level, so all connections made under this will be handled the same way. The institutions presented to the user are decided by the partner and can be configured at any point via the dashboard. Everything else is handled by the UI.

Implementation

The Consent UI is hosted by Basiq and accessed by passing a CLIENT_SCOPE. This token must be bound to the userId for security, preventing unauthorised consents:

https://consent.basiq.io/home?token={{client_token_bound_to_userId}}

Access token and userId can be obtained through the Basiq API (See the quick start guide).

The Consent flow

The Consent UI will grant a different user flow, depending on the action required. This is handled by partners passing additional parameters in the URL.

Create Consent (No action parameter, default)

Not passing any action parameters will present the user with the default Consent Flow, and should be used for first time onboarding and users that do not have an existing, valid consent against their account. This flow will cover consent as well as connecting their institutions.

Manage consent action=manage

Your user would like to manage their consent. This includes viewing their current consent including expiry, and connections they have made that your application now has access to. This screen will allow them to delete connections individually or entirely revoke the consent they have given to your organisation.

Note: Using this action when a user does not have an active user consent will result in an error.   

Connect institutions action=connect

If your end user has an existing, valid consent, they do not need to re-consent and instead can skip straight to connect any institutions. E.g. if a user has decided they would like to add more connections after already exiting the flow.

Extend consent action=extend

Your user's consent is due to expire soon, and are required to extend it in order for your application to continue to access their data.

Note: Using this action when a user does not have an active user consent will result in an error.

Update consent action=update

Your user needs to update their consent. E.g. The applications consent policy has been amended due to an increase in scope and they are required to re-authorise. A change in scope will not invalidate your users consent, however it will restrict your application from accessing data under the additional scopes until they have accepted the new consent policy.

Note: Using this action when a user does not have an active user consent will result in an error.

Here's how the process works:

action=update: When you initiate the action=update, we compare the current consent policy on the application with the active consent. This policy can be updated from the Basiq dashboard via the customised UI. If the consent policy remains the same, we automatically fall back to the action=extend, which extends the existing consent.

Different Scopes: If the scopes in the consent policy have changed, we will ask the customer to re-consent. This means they will need to agree to the updated consent.

Re-Consent Implications: During the re-consent process, the old consent is revoked. This revocation results in the deletion of all existing connections. On the subsequent screen, you will notice that the 'previously connected' institutions are displayed prominently at the top.

❗️

In essence, choosing action=update is beneficial when a partner wishes to update their existing customer consents to align with the new policy. It's crucial to be aware that executing this action will result in the revocation of all existing connections.

Reauthorise Consent action=reauthorise

The action=reauthorise parameter has been updated to enhance user experience and simplify consent management within the Basiq platform. This reauthorisation process addresses issues related to close-to-expiry connections and streamlines the extension of consent periods.

🚧

Expiring Soon Connections

For open banking type connections with an expiryDate less than 7 days away, they will be categorised under the 'Expiring soon' section, and a 'Renew' button will be visible as per the below screenshot.

Renew Button Functionality Upon clicking the "Renew" button, you will be redirected to the data holder to prolong the duration of your connections for currently shared accounts.

Authorisation Flow for Extension:

Changes in Authorisation Flow: Users will observe a minor modification in the authorisation flow when initiating the extension process. During the authorisation renewal, data holders will pre-select the accounts that users are currently sharing. It is important to note that this process may vary among different data holders.

Post-Renewal Account IDs: Our partner assures users that after following the renewal flow, the Basiq account IDs on the user's side will remain unchanged. Users can continue accessing their financial data using the same account IDs after the renewal.

The Close button navigates the user to the redirect URL page. If the redirect URL isn’t defined in the application configuration, the button remains invisible. The URL includes any state parameter provided, as well as jobId and jobIds values cached from authorisations done during the session.

State Parameter

This release enables our partners when launching the frontend flow, We allow our partners to pass a state parameter which is included in the BASIQ Consent URI when the user returns to our application. This state parameter can be decoded on the partners application side and be used to determine where to direct the user back to.

Note: The BASIQ Consent URI will look like this: https://consent.basiq.io/home?&token=${token}&action=${action}&state={yourState}

Institution parameters

If a partner knows which institution they wish to obtain credentials for, they can add an institutionId parameter to the URL. This will bypass the "Select Institution" screen and is applicable for the following flows:

• Create consent: default
• Connect institutions: action=connect
• Update consent: action=update

Note: The BASIQ Consent URI will look like this: https://consent.basiq.io/home?&token=${token}&action=${action}&state={yourState}&institutionId={institutionId}

connectionId parameter

Overview

Basiq's Consent UI facilitates a seamless user experience for handling banking connections. The connectionId URL parameter is a critical component in managing these connections, especially for reauthorisation and credential updates.

URL Structure

The basic structure of the Basiq Consent URI incorporating the connectionId parameter is as follows:

https://consent.basiq.io/home?&token=${token}&connectionId=${connectionId}

Parameter: connectionId

For Non-Open Banking Connections (Web Connections)

Existing Behavior: The connectionId parameter currently supports non-OB connections. It is used primarily for initiating a credential update flow through the Consent UI.

Usage: When a partner passes a connectionId that refers to a non-OB connection, the Consent UI triggers a workflow to update credentials.

Update credentials via Consent UI

Partners can pass a connectionId parameter in the URL to initiate a credential update flow. This only works for non-CDR connections.

Extension for Open Banking Connections

New Behavior: The connectionId parameter now also supports OB connections.

Reauthorisation Support: For OB connections, if a partner includes a connectionId in the URL, it'll kick-start the reauthorisation process. This includes handling via API calls or by using the action=reauthorise parameter.

jobIds parameter

Basiq allows your users to create multiple connections within a single flow when the Allow multiple connections feature is enabled in the Basiq dashboard. With the new jobIds parameter, you can retrieve all the jobIds from connection attempts appended to the Redirect URL.

This parameter makes it easier and more streamlined for you to track the progress of multiple connections within the same session. The Redirect URL contains all jobIds from that session, including the newest jobId like so:

http://www.your-redirect-url.com/?jobIds=123,456,789

Refer to the Dashboard configuration page for more information on how to enable the Allow multiple connections feature.

Error scenarios

Payments consent action=payment

Passing in this value would result in showing the payments consent UI. If the user has not consented to sharing data accounts then they will be directed to that step first. If the user has already shared data accounts then the payments consent will be shown.

Resource not found

You will be met with a resource-not-found error if your user does not have a current consent and you are attempting to enter a flow that requires one such as action=manage. This can be avoided by performing a check for your user's consent prior to initiating this flow. If they do not have one they should go to the default flow and give consent.

Missing attributes

A missing-attributes error may occur if your access token has not been bound to a userId. You can try use this JWT app to decode your token and confirm if it has been bound correctly. Read more about tokens here.

Full consent flow diagram