Integration guide

To take advantage of the new connections Extend functionality, check out the API reference for the connections/extend endpoint.

Have you already implemented re-auth?

The connections/extend endpoint supersedes the /reauthuri endpoint. We've designed moving across to be easy - the request structure is very similar. We recommend replacing your use of /reauthuri with connections/extend.

Step 1: Build a reconfirmation of consent screen

At present, we do not have auth dialog support for reconfirmation of consent. This means your application must include a reconfirmation of consent screen, to make sure the end-user has fully informed consent when they reconfirm.

View our guidance on how to design this user experience here.

Once consent has been reconfirmed, you can use the connections/extend.

Step 2: Call connections/extend

You will need to pass in several key pieces of information that will be used depending on the further actions required when extending. This allows TrueLayer to provide a straight forward integration which can be expanded upon overtime.

You should also provide information about the end-user at this point. This includes the user's full name and either their email or phone number.

This call does not require a valid access_token, but you must include a refresh_token in the request body for the connection you want to extend. This is so that an expired connection (no consent given in the last 90 days) can still be extended, even if you cannot generate a valid access token for it.

Step 3: Handle a successful connections/extend response

After a valid call to connections/extend, you will have received a successful response. Validation is in place to give meaningful errors if information is missing from the request, as well as informing when other issues may arise.

A successful response from connections/extend can have a different structure depending on the next steps required. A successful response will always have the field action_needed which you can use to determine what needs to happen next in the process.


Use mock bank to trigger a specific action_type

Our mock bank supports different login credentials which trigger different action types.

  • John Doe (username: john, password: doe) will return "authentication_needed"
  • John Eternal (username: john, password: eternal) will return "no_action_needed"

3.1 no_action_needed action_type

When receiving the no_action_needed action_type, store the new access token and refresh token used to continue to access account information for that connection. There is no further action required.

3.2 authentication_needed action type

When receiving the authentication_needed action type, the response will include a user_input_link. The end-user should be directed to the user_input_link. This can occur if a bank hasn't updated their APIs to support reconfirmation, or in exceptional circumstances if a bank suspects fraudulent data access is occurring.

After the end-user has gone through the bank authentication process, they will be redirected to the redirect_uri specified in your initial connections/extend. TrueLayer populates the redirection link with a code that can be used to exchange for a new access_token.

Did this page help you?