Reconnection Widget

Overview

Bank connections linked on Aerosync can stop working either because the user's consent naturally expired or because the user explicitly revoked access. As an integrator, you should treat both as explicit connection states and wire your UX and backend logic around them.

The reconnection widget can be used to allow your end user to link their exact bank account again.

Why Bank Connections Stop Working

Time / Consent-Based Expiry

This is when the underlying bank or data provider no longer considers the user's consent valid, typically after a fixed time window, even if things were working before.

Aerosync will surface this as a distinct status (for example, FAILURE) on the connection.

What happens in this state:

• You should stop attempting to refresh or pull new data for that connection
• The connectionId and account IDs will remain stable so your own references and historical data continue to work
• Your systems should treat the account as "known but inactive" rather than deleted

How to handle it:

• Use the connection status to display a "Reconnect your bank" or similar CTA in your UI instead of failing silently
• When the user chooses to reconnect, send them through your normal Aerosync bank-linking/authorization flow
• On success, Aerosync will associate the updated authorization with the existing connectionId and account IDs whenever the underlying account matches, so you do not need to manage multiple IDs for the same account
• Once reconnected, the status transitions back to ACTIVE and you can resume refreshes and data pulls as normal

User-Initiated Revocation

This is when the user explicitly removes your app's access (for example, in their bank app or a data-sharing dashboard). Technically this also invalidates access, but the intent is different and should be surfaced differently to your users.

Aerosync will expose a separate status (for example, REVOKED_BY_USER) to indicate that the user actively removed access.

What happens in this state:

• You must stop all attempts to refresh or fetch data for that connection
• The connectionId and account IDs remain, but no new data is available
• You should not treat this as a transient error; it is a user decision

How to handle it:

• Use the status and reason to display clear messaging such as: "You removed this connection at your bank, so we can't access this account anymore"

How It Works

Happy Path Example

1. User has Chase Checking Account 1234
2. User presented Reconnection Widget
3. User will be directed to reconnect a Chase account
4. User must reconnect Chase Checking Account 1234

Unhappy Path Example

1. User has Chase Checking Account 1234
2. User presented Reconnection Widget
3. User will be directed to reconnect a Chase account
4. User tries to connect Chase Checking Account 9876
5. Error is thrown to end user
6. User will be directed to link their exact same bank initially linked

Implementation

The reconnection process follows a straightforward flow: First, check the account status through the /accounts endpoint. If the connection status is FAILURE, retrieve the connectionId and initiate the Reconnection Widget. Once the user completes the reconnection flow through the widget, verify that the connection status has returned to CONNECTED. The steps below walk you through each part of this process.

Step 1: Check Account Status

To determine if a user needs to reconnect their bank account, first call the /accounts endpoint using the user's connection ID. If the bank account status is "FAILURE," you should then present the reconnection widget to the user.

For more details on checking account status, refer to the documentation on Bank Account Details.

Step 2: Configure and Present the Widget

Generate an Aerosync Token

To use the Reconnection Widget, you'll need to generate an Aerosync token with specific parameters. This token authenticates the reconnection request and identifies which connection needs to be restored.

Required parameters:

• apiKey - Your Aerosync API key
• apiSecret - Your Aerosync API secret
• aeroPassUserUUID - The user's unique identifier in Aerosync
• connectionId - The ID of the expired or revoked connection (obtained from the on-success event when the bank was originally linked)
• reconnectAttempt - Set to true to enable reconnection mode

Example token generation request:

https://api-aerosync.readme.io/reference/post_token-widget

POST /token
{
  "apiKey": "your_api_key",
  "apiSecret": "your_api_secret",
  "aeroPassUserUUID": "user_uuid_here",
  "connectionId": "conn_uuid_here",
  "reconnectAttempt": true
}

Initialize the Widget

Once you have the token, configure and initialize the Aerosync widget:

// Save the token and configure the widget
let widgetRef = openWidget({ = {
  token: "generated_token_here",
  environment: "production", // or "sandbox"
  aeroPassUserUuid: "user_uuid_here",
  ....
 });

// launch Aerosync widget with the configuration
widgetRef.launch();

The Reconnection Flow

When the widget launches in reconnection mode:

1. The user is directed to their specific bank (e.g., Chase)
2. The user enters their bank credentials on the bank's login page
3. The user completes any required authentication (OTP, etc.)
4. The user completes any additional bank-specific verification steps
5. The user confirms their account selection
6. The connection is restored with the same connectionId

When the same institution and account are selected, Aerosync will map the new authorization back onto the existing connectionId so your internal references remain intact.

After successful reconnection, the status returns to ACTIVE and your integration can resume normal operation.

Testing in Sandbox

You can test the complete reconnection flow end-to-end in the sandbox environment using our test bank. This walkthrough will help you verify your implementation before going to production.

Step 1: Link a New Bank Connection

First, create a test bank connection to get a connectionId:

1. Generate an Aerosync token (without reconnectAttempt parameter)
2. Launch the Aerosync widget
3. On the bank list page, search for and select "Aerosync Bank (MFA Trigger)"
4. Enter the test credentials:
   • Username: mxuser
   • Password: correct
5. Select either the Checking or Savings account
6. Confirm your account selection
7. Close the widget and capture the connectionId from the onSuccess event

📘

Important: Make note of which account type (Checking or Savings) you selected - you'll need to select the same one during reconnection.

Step 2: Test the Reconnection Flow

Now simulate a reconnection scenario:

1. Generate a new Aerosync token with the reconnection parameters:

{
  "apiKey": "your_api_key",
  "apiSecret": "your_api_secret",
  "aeroPassUserUUID": "user_uuid_here",
  "connectionId": "conn_from_step_1", // Use the connectionId from Step 1
  "reconnectAttempt": true
}

2. Launch the widget with the new token
3. The widget will automatically display the "Aerosync Bank (MFA Trigger)" login page - you won't need to search for it
4. Enter the same test credentials:
   • Username: mxuser
   • Password: correct
5. Select the same account type you chose in Step 1 (Checking or Savings)
   • ✅ Selecting the same account = successful reconnection
   • ❌ Selecting a different account = error (this is expected behavior)
6. Confirm your account selection
7. Close the widget

Expected Result: The bank connection is successfully re-established with the same connectionId.

Demo