Create a Finch Connect Session

Finch Connect is the interface your customers use to provide consent, approve permissions, connect their HR or payroll system, and authenticate. Finch Connect walks each employer through the appropriate flow based on the provider and auth method. Finch Connect is supported via the Frontend SDKs for JavaScript and React. You can embed Finch Connect in your application, or set up a redirect flow.

This section requires a Finch application with a client_id and client_secret. Complete Create a Finch Developer Account first.

Session Configuration

Every flow requires a Finch Connect session, created with your client_id and client_secret. Configure the session with the following parameters:

Parameter	Requirement	Description
`customer_id`	required	A unique identifier for your customer.
`customer_name`	required	The name of your customer.
`customer_email`	optional	The email associated to your customer.
`products`	required	An array of permissions your application is requesting access to. See Product Permissions for a list of valid permissions. Please note that SSN is its own product scope.
`redirect_uri`	redirect flow only	Required for the redirect flow; omit it for the embedded flow. The URI your user is redirected to after successfully granting your application access to their system. Must match one of your application’s configured redirect URIs.
`integration.provider`	optional	An optional parameter that allows you to bypass the provider selection screen by providing a valid `provider_id` from our list of Providers.
`integration.auth_method`	optional	An optional parameter that allows you to bypass the provider selection screen by providing a valid `auth_method` for a provider from our list of Providers.
`sandbox`	sandbox apps only	Selects which type of sandbox the session uses: `finch` for the Finch Sandbox, or `provider` for the provider’s test environment. Your `client_id` determines the environment, not this field.
`manual`	recommended	Set to `true` to show assisted providers alongside automated providers on the selection screen; `false` shows automated providers only. Recommended: pass `true`, then control which providers your customers see from the Integrations tab of the Dashboard — see Manage Integrations.
`minutes_to_expire`	optional	An optional value which allows you to set the number of minutes the connect session should be valid for. Defaults to 129,600 (90 days).
`connection_id`	reauthentication only	A unique identifier created when an employer successfully authenticates through Finch Connect. This ID is only used for reauthentication. You will not have a `connection_id` for the first call. For all reauthentication flows you should include the `connection_id` to avoid duplicate connections being created.

Create a Connect Session

Your backend application calls Create a New Connect Session (POST /connect/sessions). The example below shows the required parameters plus the recommended manual flag — add any optional parameters from the table above as your integration needs them.

Create a Connect session

import Finch from '@tryfinch/finch-api';

const client = new Finch({
  clientId: 'My Client ID',
  clientSecret: 'My Client Secret',
});

async function main() {
  const session = await client.connect.sessions.new({
    customer_id: customer.id,
    customer_name: customer.name,
    products: ['company', 'directory', 'individual', 'employment', 'payment', 'pay_statement'],
    manual: true,
    redirect_uri: 'https://example.com/finch/callback', // Include only for the redirect flow
  });

  console.log(session);
}

main();

Response

{
  "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "connect_url": "https://connect.tryfinch.com/authorize?session=f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Use session_id to launch the embedded flow, or connect_url for the redirect flow. If your customer has successfully authenticated (completed Finch Connect and you see a Live connection on your dashboard) and you call POST /connect/sessions using the same customer_id you passed in, Finch will prompt you to re-authenticate instead and return the following error:

Error: connection already exists

{
  "code": 400,
  "finch_code": "connection_already_exists",
  "message": "There's an existing connection for the customer_id: <session.customer_id>. Please use the /connect/sessions/reauthenticate endpoint instead.",
  "name": "bad_request",
  "context": {
    "customer_id": "<session.customer_id>",
    "connection_id": "<connection.id>"
  }
}

If your customer has not yet authenticated and you call POST /connect/sessions with the same customer_id, Finch refreshes the connect session and returns the same session_id. Use this to update the customer name or any other parameter before your customer connects. After the customer has connected, session parameters can no longer be changed. A reauthentication session can add or remove product scopes on the existing connection — pass the desired products array — or let the employer add entities to it. See Reauthentication for both.

Best Practices: Creating Sessions

DO

Always pass in a stable and unique customer_id for a given employer, and reuse the same customer_id across retries or drop-offs. Even if an employer opens the Connect session multiple times before successfully connecting, using the same customer_id ensures all attempts are tracked as a single staged session.
If you think an employer intends to connect multiple entities or payroll systems, you can append an identifier to the customer_id to differentiate the Connect sessions (e.g.: acme-1, acme-2). Visit this Help Center article for more details.

DON’T

Don’t generate a new customer_id on retries or failed connection attempts. This creates redundant staged connections and can lead to unintended behavior:
- If an employer converts using Session_Link_1, Session_Link_2 will eventually expire
- If an employer converts using both Session_Link_1 and Session_Link_2, they will inadvertently create two connections.

Reauthentication Sessions

Your application should be able to generate a Finch Connect session for reauthentication. This will avoid creating duplicate connections and ensure that the user is able to reauthenticate successfully to continue syncing data. When a connection moves to a status of reauth, call Create a new Connect session for reauthentication (POST /connect/sessions/reauthenticate) with the connection_id of that connection. The response includes a new session_id and connect_url. Because the connection_id identifies the existing connection, the employer skips provider selection and reconnects the same connection.

Launch Finch Connect

Finch provides two options to launch Finch Connect: redirect and embedded. For both options, your customer will go through the same authentication flow in Finch Connect.

Redirect Flow

Use the redirect flow if you are not using the Finch Frontend SDK or need to share a link directly with your customer, such as via email or a URL redirect.

Configure Finch Connect — Create a connect session using POST /connect/sessions. See Create a Connect Session above for details.
Share Finch Connect — Provide your customer with a link or button pointing to the connect_url. Your customer clicks it to redirect their browser to Finch Connect, hosted by Finch at https://connect.tryfinch.com, and initiate the authorization flow.
Request access — Finch Connect prompts your customer to approve the permissions your application is requesting and provide the credentials or information needed to connect their employment system.
Retrieve the authorization code — After your customer authenticates and grants access, Finch Connect redirects their browser to your redirect_uri with a short-lived authorization code.
Exchange the code for an access token — Your application exchanges the short-lived code for a long-lived access_token. See Retrieve An Access Token for details. The access_token is then used to make Finch API calls.

If your application needs to carry its own context through the flow, see Set state in the redirect flow.

Embedded Flow

Use the embedded flow if you are integrating via the Finch Frontend SDK and want your customer to complete the authorization flow within your application.

Configure Finch Connect — Create a connect session using POST /connect/sessions. See Create a Connect Session above for details.
Share Finch Connect — Provide your customer with a button that calls connect.open() with the session_id. Your customer clicks it to launch the Connect modal within your application and initiate the authorization flow.
Request access — Finch Connect prompts your customer to approve the permissions your application is requesting and provide the credentials or information needed to connect their employment system.
Retrieve the authorization code — Your application receives a short-lived authorization code via the SDK’s onSuccess callback after your customer successfully authenticates.
Exchange the code for an access token — Your application exchanges the short-lived code for a long-lived access_token. See Retrieve An Access Token for details. The access_token is then used to make Finch API calls.

If your application needs to carry its own context through the flow, see Set state in the embedded flow. Finch offers both a JavaScript and a React frontend SDK, available in the repository below. See the repository README for installation and usage instructions.

Finch Connect SDK

Pass context with the state parameter

Most integrations do not need state. Finch Connect sessions are created server-side using your client credentials, so they are not vulnerable to the CSRF attacks that state traditionally prevents. Use it only when your application needs to carry its own context through the authorization code exchange, or to meet a security requirement specific to your application. state is not accepted by POST /connect/sessions and is silently ignored if passed there. Set it when you launch the flow.

Set state in the redirect flow

Append state to the connect_url. Finch Connect returns it unchanged as a query parameter on the redirect to your redirect_uri.

Passing state in the redirect flow

https://connect.tryfinch.com/authorize?session=<session_id>&state=onboarding-step-3

Set state in the embedded flow

Pass state to connect.open(). The SDK returns it on the onSuccess event alongside the code.

Passing and reading state in the embedded flow

const connect = FinchConnect.initialize({
  onSuccess: ({ code, state }) => {
    // state === 'onboarding-step-3'
    sendToBackend({ code, state });
  },
  onError: ({ errorMessage }) => console.error(errorMessage),
  onClose: () => {},
});

connect.open({ sessionId, state: 'onboarding-step-3' });

Checkpoint + Next Step

Finch Connect is now integrated into your application’s front end. Employers can authenticate with their employment systems, which gives your application the authorization it needs to Retrieve An Access Token in the next section.

Learn more

Finch Connect Best Practices

How Finch Works

Integrations

Products

Implementation Guide

Developer Resources

Create a Finch Connect Session

Session Configuration

Create a Connect Session

Best Practices: Creating Sessions

DO

DON’T

Reauthentication Sessions

Launch Finch Connect

Redirect Flow

Embedded Flow

Finch Connect SDK

Pass context with the state parameter

Set state in the redirect flow

Set state in the embedded flow

Checkpoint + Next Step

Learn more

​Session Configuration

​Create a Connect Session

​Best Practices: Creating Sessions

​DO

​DON’T

​Reauthentication Sessions

​Launch Finch Connect

​Redirect Flow

​Embedded Flow

Finch Connect SDK

​Pass context with the state parameter

​Set state in the redirect flow

​Set state in the embedded flow

​Checkpoint + Next Step

​Learn more

Session Configuration

Create a Connect Session

Best Practices: Creating Sessions

DO

DON’T

Reauthentication Sessions

Launch Finch Connect

Redirect Flow

Embedded Flow

Pass context with the state parameter

Set state in the redirect flow

Set state in the embedded flow

Checkpoint + Next Step

Learn more