A connection exists once an access token is obtained and stored securely. Once a connection is no longer needed or requested to be deleted by the customer, calling the /disconnect endpoint will disconnect all associated access tokens for that particular connection. It is important to know how Finch defines a connection to understand what happens when a connection is disconnected.

​
Disconnect scenarios

Finch defines a connection using a connection_id. Let’s evaluate three different scenarios…

​
1. Different user credentials

CompanySame
ProviderSame
User CredentialsDifferent
In this case, even though different user credentials might be used to login (i.e. different accounts), as long as the same employer is using the same provider to login, it only counts as one connection. Thus, disconnecting the connection will disconnect all tokens for that connection.

​
2. Different companies

CompanyDifferent
ProviderSame
User CredentialsSame
Alternatively, if a customer had two different companies using the same provider, it would count as two different connections since the connection_ids are different. Thus, disconnecting one won’t disconnect the other.

​
3. Different providers

CompanySame
ProviderDifferent
User CredentialsSame
Finally, if a customer had the same company using different providers, it would also count as two different connections since the provider_ids are different. Thus, disconnecting one won’t disconnect the other.

​
Example

  • [1] User A authenticates to the provider Gusto via Finch Connect using Credentials X which exists in the Gusto provider for Company C. This creates a Connection 1 in Finch and issues an access token.
  • [2] User A authenticates to Gusto again using Credentials X for Company C (maybe with different product permissions). Another access token is created, but there is still only a single Connection 1 to Company C.
  • [3] User B authenticates to Gusto via Finch Connect as well but with Credentials Y which also exists in the Gusto provider for Company C. A new access token is created, and a new Connection 2 is created. To avoid a new connection being created in this scenario, make sure to use the reauthentication link containing the connection_id.
  • [4] User A sets up Company C using another provider called JustWorks. User A then uses Finch Connect to authenticate using Credentials Z which exists in the new JustWorks provider for Company C. This creates a new Connection 2 in Finch and issues an access token.
If any access tokens issued in scenarios 1 or 2 are disconnected, all tokens issued for Company C using the provider Gusto will be revoked. These tokens still exist technically, but they can no longer be used to call the Finch API; an Unauthorized error will be returned. However, the token is treated as a separate connection in scenarios 3 and 4. Disconnecting tokens associated with Connection 1 will not impact tokens associated with Connection 2.

​
Checkpoint + Next Step

After completing this step, you should know what will happen to a connection if an access token is disconnected. Your application should give your customers the ability to disconnect their connection, which subsequently calls the Finch Disconnect endpoint from the backend. By storing tokens securely and disconnecting connections when necessary, your application is more secure. If you plan on presenting the data back to the employer via a User Interface, it is crucial to control user access properly to ensure employment data is only viewable to the correct customer account.

​
Learn more