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
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. 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
connections/extend
responseAfter 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_type
s with mock providersOur 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
no_action_needed
action_typeWhen 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
authentication_needed
action typeWhen 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
.
Updated 5 months ago