> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tryfinch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reauthentication

> Reauthenticate a connection after Finch returns a 401 reauthenticate_user error. Covers multi-entity connections, employee permissions, and scope updates.

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](/api-reference/development-guides/errors/Error-Types)).

```js theme={null}
{
  "code": 401,
  "name": "authentication_error",
  "finch_code": "reauthenticate_user",
  "message": "Please reauthenticate user"
}
```

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](/api-reference/connect/reauthenticate-session) endpoint with the `connection_id` instead of creating a new connection session. See [Reauthentication errors](/implementation-guide/Backend-Application/Mitigate-Errors#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.

<Note>
  Reauthenticating only replaces the `access_token`. Other Finch identifiers, like `individual_id` or `payment_id`, stay the same across tokens.
</Note>

## 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`](/api-reference/management/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](/api-reference/connect/reauthenticate-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](/api-reference/connect/reauthenticate-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`](/api-reference/management/create-access-token) as usual. The response's `entity_ids` array includes the newly added entities. Call [`/introspect`](/api-reference/management/introspect) at any time to see the full list of connected entities, including each one's `status`.