Skip to main content
If Finch ever loses a connection with an employer’s provider system, we will return a 401 Unauthorized HTTP status code with a finch_code of reauthenticate_user (see Finch API errors). 
{
  "code": 401,
  "name": "authentication_error",
  "finch_code": "reauthenticate_user",
  "message": "Please reauthenticate user"
}
If an access token is returning this error, follow the reauthentication process to reconnect the employer. For multi-entity connections, if some entities require re-authentication while others remain connected, developers can continue retrieving data for the entities that are still connected. Employers using a multi-entity payroll system may add additional entities during reauthentication. However, entities that are already connected cannot be removed through the Finch reauthentication flow. If removal of an entity is required, disconnect the connection and provide a new Finch Connect link so the employer can update their entity selection. Sometimes the reauthenticating employee has different permissions than when the connection was originally authenticated. This can occur if a new employee reauthenticates the connection (for example, if the original employee leaves the company), or if the original employee’s role or permissions change. For multi-entity connections, Finch verifies that the employee reauthenticating has access to all entities originally connected. If the reauthenticating employee does not have access to one or more of those entities, the reauthentication attempt will fail and an error will be returned. To successfully reauthenticate the connection, one of the following must occur:
  • The reauthenticating employee updates their permissions in the payroll system to gain access to the missing entities
  • The developer disconnects the existing connection and creates a new Finch Connect session to establish a new connection