Merge Docs

Merge Link — Get Started

Learn how to add Merge's integration authentication component to your product.

Introduction

Merge Link is a drop-in UI component that guides your user through authorizing any integration that Merge offers.

After your user authenticates with an available integration, Merge will create a “Linked Account” for each integration, which can be viewed and managed in your Merge Dashboard.

If you want to enable your user to have more than one Linked Account per integration category, follow the instructions in this guide.

Preview of Merge Link component

Overview

Merge Link utilizes a series of tokens to securely authenticate your users’ integrations.

In the rest of this guide, you’ll set up the following functionality in your application:

  1. Request a single-use link_token from Merge to initialize an integration authorization session for your user.
  2. When your user finishes authorizing their integration, send a short-lived public_token to Merge.
  3. Exchange the public_token for a permanent account_token, which you’ll save for future API requests to Merge regarding your user’s data.
Diagram of integration authorization token flows

STEP 1

Server - Generate a link token

In your backend, create a request to fetch a link_token from Merge.

Pass in your production API key as a header.

Include the following body parameters:

  • end_user_origin_id: A unique id for the entity that will authenticate and configure their integrations through Merge Link.
  • end_user_organization_name: Your user’s organization name.
  • end_user_email_address: Your user’s email address.
  • categories: An array of the categories of integrations you would like to appear in Merge Link (e.g., [‘hris’, ‘ats’, ‘accounting’]).
  • integration (optional): If you'd like your user to skip integration selection and go directly to the configuration step of a certain integration, include the name of the integration here. To see the full list of supported integration names or more details on this feature, see Single Integration documentation.

This request will return the following:

  • link_token: Temporary token initializing your user’s integration authorization session.
  • integration_name: If your user has previously authorized an integration, the name of that integration will be returned here (otherwise null).
Server - Generate Link Token
Python
Ruby
Node
Java
Elixir
import requests

# Replace api_key with your Merge production API Key
def create_link_token(user, api_key):
    body = {
        "end_user_origin_id": user.organization.id, # unique entity ID
        "end_user_organization_name": user.organization.name,  # your user's organization name
        "end_user_email_address": user.email_address, # your user's email address
        "categories": ["hris", "ats", "accounting"], # choose your category
    }

    headers = {"Authorization": f"Bearer {api_key}"}

    link_token_url = "https://api.merge.dev/api/integrations/create-link-token"
    link_token_result = requests.post(link_token_url, data=body, headers=headers)
    link_token = link_token_result.json().get("link_token")

    return link_token

STEP 2

Client - Add Merge Link to your frontend

In your frontend, use the link_token from step 1 to open your user’s integration authorization session.

You’ll pass in two parameters:

  • linkToken
  • onSuccess: When your user completes integration authorization, the component will return a public_token via the onSuccess handler.

Pass this short-lived public_token to your backend to securely exchange it with Merge for a permanent account_token in the next step.

Client - Initiate Merge Link
React
Vue
HTML + JS
import React, { useCallback } from "react";
// In your React project folder, run:
// npm install --save @mergeapi/react-merge-link
import { useMergeLink } from "@mergeapi/react-merge-link";

const App = () => {
  const onSuccess = useCallback((public_token) => {
    // Send public_token to server (Step 3)
  }, []);

  const { open, isReady } = useMergeLink({
    linkToken: "ADD_GENERATED_LINK_TOKEN", // Replace ADD_GENERATED_LINK_TOKEN with the token retrieved from your backend (Step 1)
    onSuccess,
  });

  return (
    <button disabled={!isReady} onClick={open}>
      Preview linking experience
    </button>
  );
};

export default App;

STEP 3

Server - Exchange public token for account token

In your backend, create a request to exchange the short-lived public_token for a permanent account_token.

Server - Retrieve Account Token
Python
Ruby
Node
Java
import requests

def retrieve_account_token(public_token, api_key):
    headers = {"Authorization": f"Bearer {api_key}"}

    account_token_url = "https://api.merge.dev/api/integrations/account-token/{}".format(public_token)
    account_token_result = requests.get(account_token_url, headers=headers)

    account_token = account_token_result.json().get("account_token")
    return account_token  # Save this in your database

NEXT UP

Integrate your backend with Merge's Unified API

Now that you've added the ability for your users to authorize integrations from your product, let's integrate your backend with Merge.

Add Merge's SDK to your backend