Reconnecting Accounts
How users can easily re-authorize their payroll connections.
Continuous access#
Argyle's platform keeps every payroll connection alive for as long as the associated payroll system allows.
In most cases, once a user connects a payroll account, the connection stays alive indefinitely. 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.
Why accounts disconnect#
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!
90% of all payroll accounts require that users complete an additional multi-factor authentication (MFA) step.
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.
Returning users to Link#
User 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.
Caution:
You must re-send invites (API) or send the user the original invite URL (Console) for account re-connections. Sending a new invite will result in duplicate users.
Once the user returns to Link, they can access their previous connections in the upper-right of the search screen to take additional actions such as reconnecting a disconnected account in one-click (no login credentials necessary).
Shareable URLs#
If a user originally reached Link through a shareable URL, the user can return to Link and access their connected accounts through the same original URL. 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.
Embedded Link#
If you are embedding Link within your website or application, users can be sent directly to a disconnected account using the optional accountId Link initialization parameter. Users will only need to select Reconnect to re-establish the account connection, and will not need to re-enter their login credentials.
1accountId: "<ID of the disconnected account>"
Revoking access#
Users can revoke access to their accounts at any time by emailing us at [email protected].
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.
If an account is revoked by the user, or deleted via Console or via the API, and the user later connects the same payroll account in Link, a new account ID will be created that is distinct from the original revoked/deleted account.
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.
When subscribing, make sure to set include_resource to true using the config parameter to always receive a payload with the updated account's details.
To determine whether an accounts.updated webhook was triggered by an account disconnection, examine the connection.status field of the account object included in the webhook payload. 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.