Connection & Session ID Migration Guide

Last updated: December 16, 2025

Introduction

Finch has introduced a new set of IDs to help streamline connection management. Once adopted, Finch users will be able to easily track employers through every step of the Finch Connect process.

The following guide outlines the process required to implement Connection ID and how to enable secure session URLs (using Session ID) in Finch Connect.

Summary

There are two new concepts in our API:

  1. Connection ID is a unique identifier created when an employer successfully authenticates through Finch Connect. This new field makes it easier to manage connections and track connection statuses. Connection ID will be included in webhook events.

  2. Session ID is a unique identifier used to launch Finch Connect sessions. To receive a Session ID, you will provide Finch with a unique identifier for the employer you wish to authenticate. You can then use the Session ID to generate a secure session URL. Session IDs will also enable you to monitor each stage of the session, track where employers drop off, and get deeper visibility into authentication errors.

All Finch users will need to adopt both IDs before July 31, 2025 to avoid service interruption.

Timeline

  • Sept 24th, 2024

    • Connection ID and Session ID are available in the API

  • Oct 29th, 2024

    • A single connection can no longer support multiple accounts.

    • Authentication progress tracking becomes available in the Dashboard

  • Jan 1st, 2025

    • Finch begins billing using Connection ID (instead of Company ID)

  • July 31, 2025

    • Support for static Connect URLs are no longer supported

  • August 29, 2025

    • Static Connect URLs are fully deprecated

 

How to Implement Connection ID

Overview

Finch now supports connection_id through the /introspect endpoint.

Previously, a single connection could be tied to multiple accounts of different types. Each account could also contain multiple access tokens. This new model ungroups accounts from connections and instead uses a stable connection_id to represent connections.

While previously developers were instructed to use the account_id and company_id to manage connections, we now ask that developers use connection_id instead.

You may continue to store the account_id and company_id, but these values may change if an employer is asked to re-authenticate. The connection_id will remain constant.

Please note: account_id and company_id will eventually be deprecated.

 

Step 1: Capture the connection_id

  1. Complete the steps in the Quickstart guide to retrieve an access token

  2. Exchange the authorization code for an access token

  3. Get the connection_id from the access token response payload

  4. Store the connection_id in your database

You do not need to make any changes to how you store account_id or company_id; Finch will continue to return these IDs in /introspect.

account_id and company_id will be considered deprecated IDs so please use  connection_id as the stable identifier for connections.

Step 2: Migrate existing connections 

Existing connections in your database will need to be assigned a connection_id. To do this, make a request to /introspect, read the connection_id in the response, and store the connection_id in your database. 

Note: Your customers do not need to re-authenticate as part of this migration.

Step 3: Consider webhooks (if applicable)

Once you perform this migration, you will need to use the connection_id from webhook events moving forward. 

How to Implement Session ID

Finch now supports session_id, which will enable secure session URLs, session tracking, and smart re-auth.

  • Secure session URLs: Generate unique Connect URLs for employers with backend-defined properties. These URLs cannot be tampered with by employers or other parties.

  • Session tracking: Track when an employer begins a Finch Connect session, selects a provider, enters their credentials, and completes authentication in the Dashboard.

  • Smart re-auth: Lock in a Finch Connect configuration for a faster re-authentication experience. For example, if an employer connected their BambooHR account using admin credentials, they would immediately jump to the BambooHR credentials screen during re-auth.

Step 1: Update your authentication flow

Create a Connect session

Using the configuration params described in the above sections, your backend application will make a call to POST /connect/sessions to create a connect session for your customer. When creating the connect session, include customer_id, customer_name, and any optional fields listed below.

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

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

async function main() {
  const createConnectSessionResponse = await finch.connect.sessions.new({ 
	  products: ["company", "directory", "individual", "employment", "payment", "pay_statement"],
	  customer_id: customer.id, // Your internal customer ID 
	  customer_name: customer.name, // Your customer's name
	  customer_email: customer.email, // The email associated to your customer (optional)
	  integration: { // (optional)
			  provider: 'adp_run', // The provider you want to show up in connect (optional)
			  auth_method: 'credential' // The auth method of the provider to show up (optional)
	  },
	  minutes_to_expire: 20160, // How long you want the session to last for (defaults to 14 days)
	  redirect_uri: '' // The URI to redirect to for the redirect connect flow (options)
	  sandbox: false // create a sandbox session for a sandbox app (optional)
	  manual: false // A value that, when set to true, displays both Automated and Assisted providers on the selection screen (optional) 
  });

	/**
	 * { 
	 *   "session_id": "",
   *   "connect_url": ""
   * }
	**/
  console.log(createConnectSessionResponse); 
}

main();

If your customer has successfully authenticated and you call POST /connect/sessions using the same customer_id, Finch will prompt you to re-authenticate instead and return the following error. 

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

If your customer has not yet successfully authenticated and you call POST /connect/sessions using the same customer_id, Finch will simply refresh the connect session and return the same session_id. You can do this if you wish to update the Customer Name or any other parameter before your customer connects. If you wish to update any parameters after the customer has connected, you will need to use POST /connect/sessions/reauthenticate

Best Practices

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

  • Avoid generating new customer_ids on retries or failed connection attempts. This results in multiple redundant staged connections and could result in 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

Launch Finch Connect

Using the response of the API call above, either launch Finch Connect by passing the session_id to the Finch Connect SDK or direct your customer to the provided URL.

Redirect Flow 

https://connect.tryfinch.com/authorize?session=

Embedded Finch Connect

Using React SDK

import React, { useState } from "react";
import { useFinchConnect } from "@tryfinch/react-connect";

const App = () => {
  const [code, setCode] = useState(null);

  const onSuccess = ({ code }) => setCode(code);
  const onError = ({ errorMessage }) => console.error(errorMessage);
  const onClose = () => console.log("User exited Finch Connect");

// 1. Initialize Finch Connect
  const { open } = useFinchConnect({
    sessionId: "    onSuccess,
    onError,
    onClose,
});

// ...
};

 

Using javascript SDK


  <html>
  <body>
    <script>
      const onSuccess = ({code}) => {
        // exchange code for access token via your server
      }
      const onError = ({ errorMessage }) => {
        console.error(errorMessage);
      }
      const onClose = () => {
        console.log('Connect closed');
      }
      const connect = FinchConnect.initialize({
        sessionId: "<session-id",  // gotten from the /connect/sessions API call
        onSuccess,
        onError,
        onClose,
      });
    </script>
  </body>
</html>

Step 2: Update your re-authentication flow

Create a Connect re-authentication session

In your backend application, make a call to POST /connect/sessions/reauthenticate to create a connect re-authentication session for your customer. Use the session_id to create a re-authentication connect session. This will lock the Connect UI to the original implementation preventing employers from selecting a different provider or implementation when prompted to re-authenticate.

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

const client = new Finch({
  accessToken: 'My Access Token',
});

async function main() {
  const createConnectSessionResponse = await finch.connect.sessions.reauthenticate({ 
	  products: ["company", "directory", "individual", "employment", "payment", "pay_statement"],
	  connection_id: '532...' // Finch connection ID for your customer
	  minutes_to_expire: 20160, // How long you want the session to last for (defaults to 14 days)
	  redirect_uri: '' // The URI to redirect to for the redirect connect flow (options)
  });

	/**
	 * { 
	 *   "session_id": "",
   *   "url": ""
   * }
	**/
  console.log(createConnectSessionResponse); 
}

main();

Launch Finch Connect

Using the response of the API call above, either launch Finch Connect by passing the session_id to the Finch Connect SDK or direct your customer to the provided URL.

 

Redirect Flow

https://connect.tryfinch.com/authorize?session=<session ID from response>

Embedded Finch Connect

Using React SDK

import React, { useState } from "react";
import { useFinchConnect } from "@tryfinch/react-connect";

const App = () => {
  const [code, setCode] = useState(null);

  const onSuccess = ({ code }) => setCode(code);
  const onError = ({ errorMessage }) => console.error(errorMessage);
  const onClose = () => console.log("User exited Finch Connect");

  // 1. Initialize Finch Connect
  const { open } = useFinchConnect({
    sessionId: "

Please refer to the Finch Connect Implementation Guide for additional details.

Step 3: Test in sandbox 

Once you have added the session_id to your re-authentication flow, you can test the implementation in the Finch Sandbox.

Complete the steps in the Quickstart guide to retrieve an access token. Make sure to add "sandbox": "finch" when creating the connect session. 

curl  \\
-X POST \\
-H "Content-Type: application/json" \\
--data-raw '{
    "client_id": "",
    "client_secret": "",
    "code": "",
    "redirect_uri": ""
}'

Using this token, call the Introspect endpoint to read the connection_id.

{
  "client_id": "25ea8bd8-f76b-41f9-96e3-1e6162021c50",
  "client_type": "production",
  "connection_type": "provider",
  "company_id": "87eb4bc3-f76b-35e7-78d2-8f7822021d73",
  "account_id": "ca23fd65-5a0c-4f8b-a0fa-7853fd6f5768",
  "connection_id": "9289c95e-9162-4221-a850-b8ee135d4d20",
  "products": [
    "company",
    "directory"
  ],
  "username": "johndoe@tryfinch.com",
  "payroll_provider_id": "gusto",
  "manual": false,
  "authentication_methods": [
    {
      "type": "assisted",
      "connection_status": {
        "status": "pending",
        "message": "This employer has created a token, and we are waiting for access to its provider"
      }
    },
    {
      "type": "credential",
      "connection_status": {
        "status": "connected",
        "message": "This employer is working as expected"
      }
    }
  ]
}

Prompt re-authentication by updating the connection_status to reauth using the sandbox endpoint Update a sandbox account.

Pass the session_id into your re-authentication flow. If the employer is prompted to re-authenticate, they can bypass the steps of Finch Connect they’ve already completed. For example, an employer opening Finch Connect could be taken directly to the BambooHR Oauth log-in screen (if that was their prior configuration).

Step 4: Implement smart re-authentication

To take advantage of session tracking and smart re-auth for existing connections, you will need to make a request to POST /connect/sessions/reauthenticate and pass in the connection_id. Read the session_id in the response and use this session_id in your re-auth flow. 

Conclusion

Please contact your Developer Success Engineer or developers@tryfinch.com if you have any questions or need assistance.