Create a Finch Connect Session

​

Session Configuration

​

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 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 wand to show up in connect (optional)
			  auth_method: 'credential' // The auth method of the provider to show up (optional)
	  },
	  minutes_to_expire: 43200, // How long you want the session to last for (defaults to 30 days)
	  redirect_uri: '' // The URI to redirect to for the redirect connect flow (optional)
	  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": "<A unique session ID that can be used with embedded connect>",
   *   "connect_url": "<The url of the connect session for the redirect flow>"
   * }
	**/
  console.log(createConnectSessionResponse);
}

main();

{
    "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>"
    },
  }

​

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

• 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.

​

Reauthentication Sessions

​

Launch Finch Connect - choose your preferred flow (redirect or embedded)

• The redirect flow is helpful in instances where you do not have a user interface and will share a link to Finch Connect with your customer, such as in an email or a link in your application.
• The embedded flow is helpful when you want to host the authorization experience yourself, such as in a web application or mobile app. This allows you to keep your users within your application while they go through Finch Connect.

​

Redirect Flow

1. Open Finch Connect — Your application redirects your user’s browser to Finch Connect to initiate the authorization flow.
2. Obtain consent — Finch Connect prompts your user to log in to their employment system and grant your application access to the permissions you are requesting.
3. Retrieve the authorization code — If your user successfully connects and grants your application access to their system, Finch Connect will redirect their browser to a specified redirect_uri with a short-lived authorization code.
4. Exchange the code for an access token — Before sending API requests, your application will exchange the short-lived code for a long-lived access_token that your application will use to call the Finch API to retrieve data. Please read the Retrieve An Access Token section for more details on how to exchange the code for an access token.

​

Embedded Finch Connect

NOTE: You should not include a redirect_uri if using the embedded flow. Because the entire flow is already self-contained in your app, no redirect is necessary.

• React SDK: If you’re using React as your frontend framework, use the React SDK. Import the Finch Connect component and include it in your application. You can find examples and usage instructions in the SDK documentation or continue to follow this tutorial. - npm install --save @tryfinch/react-connect - yarn add @tryfinch/react-connect
• JavaScript SDK: If you’re using a different frontend framework or vanilla JavaScript, use the pure JavaScript SDK. Include the Finch Connect library in your application, either by adding a script tag to your HTML file or by importing it as a module.
• <script src="https://prod-cdn.tryfinch.com/v1/connect.js"></script>

  Since Finch Connect is an iFrame that requires interactivity, the HTML page that is loading Finch Connect must be served from a server. If the page is hosted statically, Finch Connect will not work properly.

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: "<session-id", // gotten from the /connect/sessions API call
    onSuccess,
    onError,
    onClose,
  });

  // ...
};

<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>

​

Implement the authentication flow in your application

const App = () => {
  // ...

  // 2. Display Finch Connect
  return (
    <button type="button" onClick={() => open()}>
      Open Finch Connect
    </button>
  );
};

<html>
  <body>
    <button id="connect-button">Open Finch Connect</button>
    <script>
      const button = document.getElementById('connect-button');

      const connect = FinchConnect.initialize({
        ...
      });
      button.addEventListener('click', () => {
        connect.open();
      })
    </script>
  </body>
</html>

​

Listen for events

1. onSuccess: This event is triggered when the user completes the authentication process. It returns an authorization code that you will use to obtain an access_token in the next step. Pass this authorization code securely and temporarily to the access token exchange function. Please read Retrieve An Access Token section for more details on how to exchange the code for an access token.
2. onError: This event is triggered if there’s an issue during the authentication process. Your application should handle this error gracefully, either by displaying an error message to the user or retrying the authentication flow.
3. onClose: This event is triggered when a user exits the Finch Connect model, either by closing the modal or clicking outside the modal.

​

Checkpoint + Next Step

​

Learn more

• Finch Connect Best Practices