Configure Auth Methods

Employers authenticate through Finch Connect using one of four methods: OAuth, credentials, API token, or assisted. This guide covers each method, when you have a choice between them, and how to handle authentication fallback and reauthentication.

​

Authentication Methods

Which methods are available depends on what each provider’s system offers. Most providers offer a single method, so the employer follows one path with no selection to make. A small number of automated integrations support both API token and credentials — for those, you decide whether to offer both and which one to present first. Authentication method affects which fields and functionality you can access, so check Field Support for a provider’s field coverage by method before deciding what to enable. See Set Up Preferred Authentication Methods Per Provider for how to configure it.

​

OAuth

With OAuth, the employer authorizes Finch through the provider’s own authorization flow. The employer signs in on the provider’s site rather than sharing credentials with Finch, and the provider grants Finch access to the approved data.

​

Credentials

The credentials method lets employers set up a connection by logging in with an administrator username and password. It is the lowest-friction option for employers connecting a provider through Finch. When possible, Finch will automatically set up a separate third-party administrator or accountant user behind the scenes to keep this connection active indefinitely. This will be noted on the credentials log in screen. If an employer cannot log in with credentials after 3 attempts, they can still establish a connection through Authentication Fallback.

​

API Token

The API token method uses API keys supplied by the provider to establish a connection. Once set up, these connections very rarely need re-authentication. Finch will guide employers through each step required to obtain an API key from their provider. See our authentication guides for details. A few providers charge employers for access to their API token. If you have a Help Center login, see Costs & Fees for Employers for the list.

​

Assisted

Assisted is the authentication method for assisted integrations, which require a Pro or Premier plan. In this method, Finch provides the employer with instructions to create a new admin or accountant user in their system. Finch’s operations team then uses that connection to refresh data every 7 days. Re-authentication will only be required if the user is removed or loses the necessary permissions.

​

Set Up Preferred Authentication Methods Per Provider

While authentication method will often come down to which fields or functionality is needed, you have the flexibility to decide which to make available for your end customers and their order of priority. You can set primary and secondary authentication methods for each provider, and even hide specific methods if desired. All of this is possible through the Finch Dashboard. For example, if you want to offer only the API token method for Bob, Finch can hide the credentials-based method for that provider in Finch Connect.

​

Enable or Disable Authentication Methods Globally

You can also disable an authentication method globally using the Settings page in the Dashboard. These settings will apply automatically to any new integrations.

​

Authentication Fallback

Authentication Fallback lets employers authorize through Finch Connect even when Finch is experiencing intermittent issues with a provider. It is enabled by default. Finch Connect attempts to authenticate with credentials first. If that fails, Finch Connect prompts the employer to set up Finch as a third-party administrator in their HRIS or payroll system using a set of manual instructions. Depending on the provider this happens immediately or after a set number of failed attempts. Until Finch processes this invitation, requests made with the token return a 202 response code. Once Finch has established the connection, data will flow through the Finch API just like any other automated connection. Authentication Fallback is available for the following providers:

• ADP Workforce Now
• ADP Run
• Quickbooks
• Paychex
• Paycom
• Sequoia One
• Square Payroll

To turn off Authentication Fallback, reach out to your Developer Success Representative. Make sure your application handles 202 response codes from Finch.

​

Manage Re-Authentication

Finch maintains connections as long as possible, but a connection can still require reauthentication — for example, when an employer changes security settings or permissions on their account, or when a provider makes a breaking change to their infrastructure. When that happens, the employer completes Finch Connect again. Create the session with POST /connect/sessions/reauthenticate and the connection’s connection_id. Because the connection_id identifies the existing connection, the employer skips the steps they already completed — including provider selection — and Finch reconnects the same connection instead of creating a duplicate. Completing reauthentication creates a new access_token for that connection. Save the new token in your database and use it for subsequent requests.

​

Identify connections that require re-authentication

In the API, a connection that requires reauthentication returns an error with the HTTP status code 401 and a finch_code of reauthenticate_user. In the Finch Dashboard, the Connections page lists every connection that requires reauthentication. When any connection needs it, a banner appears at the top of the page — click the banner to filter to the connections that need action from the employer.

​

Set up re-auth notifications

To increase conversion, use in-app or email notifications to tell your user there is an issue with their connection, why reconnecting matters, and the steps they need to follow to reconnect. Create the reauthentication session with the connection’s connection_id so the employer reconnects the existing connection instead of creating a duplicate. If your application doesn’t store the connection_id, read it from the /introspect endpoint using the connection’s access_token. Two options for presenting the reconnection flow to your users:

1. Prompt your user to log on to their application dashboard where you can present them the UI to go through Finch Connect again.
2. Send your user a reauthentication link. Call POST /connect/sessions/reauthenticate with the connection_id, then share the connect_url from the response. Set redirect_uri on the session to return the user to their application dashboard after a successful reconnection. See Reauthentication Sessions.