Reconnecting Accounts

How users can easily re-authorize their payroll connections.

Returning users to Link#

Embedded Link#

If you are embedding Link within your website or application, users can be sent directly to an account by including the optional accountId parameter in your Link initialization code.

1accountId: "<ID of account>"

If the user is sent to a disconnected account, they will only need to select Reconnect to re-establish the account connection, and will not need to re-enter their login credentials.

Invites#

If the user was originally sent an invite via Console or via the API, the user can return to Link any time using the same URL hyperlink included in the invite, which does not expire.

In Console, invites can be resent by hovering over the user and clicking Resend, or the direct hyperlink can by copied by hovering over Sent by [name] and shared directly with the user.

Once the user returns to Link, they can access their previous connections in the upper-right of the search screen to take additional actions, including reconnecting a disconnected account (no login credentials required).

Shareable URLs#

If a user originally reached Link through a shareable URL, the user can return to Link and access, manage, and reconnect their accounts through the same original URL hyperlink. A copy of the shareable URL associated with an individual user can be found in the Connections page of Console. See the reconnecting users section of our Shareable URLs Guide for more information.

Adjusting Link's initial screen#

Returning users can be sent directly to their connections page instead of Link search:

1. Create or edit an existing Flow in Console.
2. Toggle ON the General Setting that says: "Show Your connections as the initial screen for returning users."
3. Save the Flow, copy its Flow ID, and include it in your Link initialization using the flowId optional initialization parameter.

Why accounts disconnect#

Argyle's platform keeps every payroll connection alive for as long as the associated payroll system allows. Once a user connects a payroll account, the connection stays alive indefinitely whenever possible. This allows Argyle to continuously scan and retrieve any new data that is added to the user's payroll account, giving you ongoing data refreshes as new paystubs or payroll documents become available.

Similarly to how bank account connections with third party apps need to be refreshed periodically, some payroll systems require users to re-authenticate their connections from time to time. If an account becomes disconnected, payroll data can still be retrieved via Console or the API, but ongoing data refreshing will be paused until the account is reconnected by the user.

Types of disconnections#

Re-authorization needed#

Some payroll systems have automatic log-outs after a set period of time. Once Argyle scans a connected payroll system and finds the user has been logged out, both Console and the API will display an auth_required error in the account's details:

• If a disconnection occurs, have the user return to Link.
• The user can re-establish the connection by simply selecting Reconnect. No need to re-submit login credentials!

Expired credentials#

Some payroll systems require users to reset their passwords periodically. When this occurs, an expired_credentials error will be shown in the account's details.

• When credentials expire, have the user return to Link.
• On the account's login screen, a Login help button will take the user to their payroll system's platform. After the user resets their username or password, they need to return to Link and enter their updated credentials to re-establish the connection.

Simulating disconnections#

When Console is in Sandbox mode, Flows provides an error testing feature that lets you simulate account disconnections.

Visit our Sandbox Testing Guide for more information on error testing in Console and via the API.

Revoking access#

Within Link, users are shown which payroll accounts they have previously connected. After selecting a connected account, users are always presented with an option to revoke access to the account. After revoking access, data from the payroll account will no longer be retrievable through Console or the API.

For more information on permissioned access and privacy, visit our data security guide.

Webhooks#

We recommend subscribing to the accounts.updated webhook to be notified when an account becomes disconnected.

To determine whether an accounts.updated webhook was triggered by an account disconnection:

1. Examine the connection.status field of the account object included in the webhook payload.
2. If the value of connection.status is error, and the error_message is either auth_required or expired_credentials, an account disconnection has occurred.

Subscribe to the accounts.removed webhook to be notified when a user revokes access to one of their connected accounts.