Manage Connections

Every access token obtained is associated with a connection. Therefore, to prevent mixing up data across different users or employers, it is important to make sure you associate each access token with the correct connections in your application. Implementing a system to track the relationship between your customers and their corresponding access tokens is recommended.

​

Define connections

Finch defines a connection using a connection_id. A connection exists once an access token is obtained.

There are three types of scenarios to keep in mind when thinking about connections:

1. Multi-Account
   • Different Logins - When two employees at the same company connect to the same provider using different user credentials (or API tokens).
   • Permissions - When a company connects multiple times but with different API permissions (Organization, Payroll, Deductions, etc.).
2. Multi-Provider
   • Migration — When a company migrates from one provider to another and partial data is stored in each.
   • Foreign workers — When a company has foreign contractors or employees and utilizes a separate provider to manage those individuals.
3. Multi-Entity
   • Pay Groups — When a company has a separate entity per payroll group to pay each group on different cadences.
   • Legal Entities — When a company has separate legal entities usually in the form of divisions (corporations & LLCs), franchises (LLCs), or business units (corporations & LLCs).
   • Professional Employer Organizations (PEO) - When a company is partnered with a PEO that performs various administrative tasks on behalf of multiple companies.

In the 1) Multi-Account scenario, a single connection is created, even though multiple accounts were used to log in.

In the 2) Multi-Provider scenario, a new connection is created for every new provider connected. Even though it is the same company, there are multiple connections because the provider_id is different for each access token.

In the 3) Multi-Entity scenario, a new connection may be created for every company “entity” connected.

​

Isolate connections

Given these scenarios, your application must be able to manage multiple connections per customer and keep each connection and its corresponding access tokens isolated from the rest.

You should store access tokens in your system using the connection_id.

• provider_id = the payroll provider associated with the access token.
• customer_id = a unique identifier that you create to manage your customers internally

You define the customer_id; Finch defines the connection_id (more on this below).

​

Introspect endpoint

The best way to retrieve the unique ids associated with an access token is by calling the Introspect endpoint. It will return a JSON body containing account information associated with the access_token.

{
  "account_id": "d8ef1814-5913-492f-b5c0-a16e2d6432c9",
  "client_id": "25ea8bd8-f76b-41f9-96e3-1e6162021c50",
  "connection_id": "6dab009c-77c8-43d9-8f81-e093f7c65bc1",
  "company_id": "87eb4bc3-f76b-35e7-78d2-8f7822021d73",
  "payroll_provider_id": "gusto",
  "products": [...],
  ...
}

​

Example

A simple example is a 1:1 connection association. It can be represented by a single database table with columns for customer_id and the associated access_token. You can use a unique constraint on the customer_id column to ensure that each user can have only one associated access_token.

However, in production, you will want to handle the more complex connection scenarios above which have a 1:Many relationship.

This can be represented by two database tables: the Customers table one stores the customer_id and the Connections table stores the connection_id which references back to a customer_id.

In this realistic example:

• connection_id represents the unique finch variables that define a connection.
• A “composite unique constraint” can be set on connection_id  values which means that while each of these connections can contain the same values individually, the combination of these values must be unique (hence a unique connection).

Now, when you insert data into the Connections table, you’ll need to ensure that the connection_id is unique for each row, while the access_token inherently remains unique for each row as well. The connection_id (when combined with data from the Finch /company endpoint) is going to be able to tell you which employers are attached to each customer.

​

Enabling multiple connections with Finch Connect

To have your customer create multiple connections in your application, your “onboarding” flow or “connections” page must allow them to go through Finch Connect multiple times.

Below is an example User Interface. You can present your customers with a page showing all of their current connections and provide the option to connect more accounts, providers, or company entities.

​

Edge cases

​

Reauthentication

In reauthentication situations, your customer should be prompted to reconnect their provider again before continuing to use the application. When the Finch Connect flow is completed, a new access token will be generated. Simply replace the old token with the new token and start making Finch API requests with the updated token like before.

​

Repeating employees

In the multi-provider or multi-company scenarios, if your application is combining data across multiple access tokens, you may need to reconcile employees between responses in order to merge employee data properly.

​

Checkpoint + Next Step

​

Learn more

• Control User Access
• Set Up Finch Connect
• Reauthenticating Connections
• Reconcile Employees
• Integration Types: Automated