Extend endpoint integration guide

An overview of how to get started with the /connections/extend endpoint.

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 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 actions required when extending the connection. This allows TrueLayer to provide a straightforward integration which can be expanded upon over time.

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. The user_id is the UUID that was automatically generated for the user when they initially created the connection. You do not need to include any fields specifying the user's bank details.

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 receive 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 may 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.

📘

Test action_types with mock providers

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 you have received the no_action_needed action_type, store the new access token and the refresh token you used. These enable you 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 that data access is occurring fraudulently.

After the end user has gone through the bank authentication process, they are 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.