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, EXPIRED_CONSENT) 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

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 "EXPIRED," 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

Pass in the connectionId and aeroPassUserUUID within the Aerosync Widget Configs.

Present the Aerosync Reconnection widget to the end user.

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.

at Aerosync will preserve connectionIds when the same account is reauthorized.