Skip to main content
A Finch connection breaks when the authentication credentials Finch uses to access the employer’s provider system no longer work. When this happens, the connection’s status changes to reauth, and Finch returns a 401 Unauthorized HTTP status code with a finch_code of reauthenticate_user (see Finch API errors).
If an access token returns this error, the employer must reauthenticate by completing a Finch Connect Reauthentication session. Make sure your application uses the reauthentication session endpoint with the connection_id instead of creating a new connection session. See Reauthentication errors for more details about this error.

​
Notify the employer to reauthenticate

Notify the employer as soon as a connection needs reauthentication — for example with an in-app banner or email — so they can reauthenticate before missing a data sync. Prompt them to reauthenticate through your existing Finch Connect flow, whether that’s directly in your app or by sending them a link.
Reauthenticating only replaces the access_token. Other Finch identifiers, like individual_id or payment_id, stay the same across tokens.

​
Reauthenticate multi-entity connections

If some entities in a multi-entity connection require reauthentication while others remain connected, developers can continue retrieving data for the entities that are still connected. Employers using a multi-entity payroll system can add additional entities during reauthentication. Finch also verifies that the reauthenticating employee has access to all entities originally connected. If the employee does not have access to one or more of those entities, the reauthentication attempt fails and Finch returns an error. To resolve this:
  • The employee must gain access to the missing entities in the payroll system, or
  • The developer uses /disconnect-entity to remove the entities the employee cannot access, then reauthenticates the connection for the remaining entities
If an entity is in reauth status and the employer wants to remove it instead of reauthenticating it, use /disconnect-entity to remove that entity from the connection. The other entities and the access token are not affected.

​
Reauthenticate with a different employee

The employee who reauthenticates a connection does not have to be the employee who originally connected it — any employee can reauthenticate, as long as they have sufficient permissions in the payroll system to access the data the connection is authorized for. This commonly comes up when the original employee leaves the company or when their role or permissions change. If the reauthenticating employee does not have sufficient permissions, the reauthentication attempt fails and Finch returns an error. To resolve this:
  • The employee gains the required permissions in the payroll system, or
  • A different employee with sufficient permissions reauthenticates the connection instead

​
Update product scopes using a reauthentication session

A reauthentication session can be initiated specifically to update product scopes — the connection does not need to be in reauth status to do this. Pass the desired products array to reauthenticate a session to add or remove scopes on an existing connection without creating a new one.

​
Add entities using a reauthentication session

A reauthentication session can also be initiated to let an employer add entities to an existing connection — the connection does not need to be in reauth status to do this. Create a reauthentication session and prompt the employer to complete it in Finch Connect. If entities exist that aren’t yet connected, the employer can select them there. After the employer completes Finch Connect, exchange the resulting authorization code through /auth/token as usual. The response’s entity_ids array includes the newly added entities. Call /introspect at any time to see the full list of connected entities, including each one’s status.