Link
Link is a UI component that guides your app's user through setting up an integration.

Add Link to Your Product
Link utilizes a series of token exchanges to securely authenticate your users' integrations.
In this guide, you'll set up the following in your application:
- Get a
link_token
to initialize a Link session for your end user. - Make Link appear in your frontend.
- Swap for an
account_token
, which authenticates future requests to the Unified API.

Backend – Get Link Token
In your backend, set up a POST request to initialize a Link session and get alink_token
from this URL:
https://api.merge.dev/api/integrations/create-link-token
Pass in your Production Access API key as a header.
Configure your Link with the following parameters:
Parameter | Type | Description |
end_user_origin_id | String | Unique ID for your end user. |
end_user_organization_name | String | Your end user's organization. |
end_user_email_address | String | Your end user's email address. |
categories | Array | The integration categories to show in Merge Link.["hris", "ats", "accounting", "ticketing", "crm", "mktg", "filestorage"] |
integration Optional | String | Identifier of third-party platform to skip Link menu for. See Single Integration guide. |
The response will include the following fields:
Parameter | Type | Description |
link_token | String | Temporary token to initialize your end user's Link. |
integration_name | String | The name of any previously connected third-party platform (otherwise null ). |
Pass the link_token
to your frontend to display Link in step 2.
1import requests23# Replace api_key with your Merge production API Key4def create_link_token(user, api_key):5 body = {6 "end_user_origin_id": user.organization.id, # unique entity ID7 "end_user_organization_name": user.organization.name, # your user's organization name8 "end_user_email_address": user.email_address, # your user's email address9 "categories": ["hris", "ats", "accounting", "ticketing", "crm"], # choose your category10 }1112 headers = {"Authorization": f"Bearer {api_key}"}1314 link_token_url = "https://api.merge.dev/api/integrations/create-link-token"15 link_token_result = requests.post(link_token_url, data=body, headers=headers)16 link_token = link_token_result.json().get("link_token")1718 return link_token
Each end_user_origin_id
can have a maximum of one Linked Account per category.
For example, each ID can have up to one HR, Payroll, and Directory, one ATS, one Accounting, one Ticketing, one CRM, one Marketing Automation, and one File Storage integration simultaneously.
If you want to link multiple accounts for the same user, learn more in our help center.
Frontend – Make Link Appear
In your frontend, use the link_token
from step 1 to open Link.
Pass in these parameters:
Parameter | Type | Description |
linkToken | String | Initializing token from step 1. |
onSuccess | Function | Callback to handle public_token , which is returned when your end user finishes their Link session. |
tenantConfig? | Object | Optional parameter to specify a tenant. For example, to point to our EU multi-tenant, apiBaseURL should be set to https://api-eu.merge.dev . |
Pass the public_token
to your backend to securely swap it for an account_token
in step 3.
1import React, { useCallback } from "react";2// In your React project folder, run:3// npm install --save @mergeapi/react-merge-link4import { useMergeLink } from "@mergeapi/react-merge-link";56const App = () => {7 const onSuccess = useCallback((public_token) => {8 // Send public_token to server (Step 3)9 }, []);1011 const { open, isReady } = useMergeLink({12 linkToken: "ADD_GENERATED_LINK_TOKEN", // Replace ADD_GENERATED_LINK_TOKEN with the token retrieved from your backend (Step 1)13 onSuccess,14 // tenantConfig: {15 // apiBaseURL: "https://api-eu.merge.dev" /* OR your specified single tenant API base URL */16 // },17 });1819 return (20 <button disabled={!isReady} onClick={open}>21 Preview linking experience22 </button>23 );24};2526export default App;
Backend – Swap public token for account token
In your backend, create a request to exchange the short-lived public_token
for a permanent account_token
.
Important: Securely store this account_token
in your database for authenticating future API requests to the Unified API regarding the end user's data.
1import requests23def retrieve_account_token(public_token, api_key):4 headers = {"Authorization": f"Bearer {api_key}"}56 account_token_url = "https://api.merge.dev/api/integrations/account-token/{}".format(public_token)7 account_token_result = requests.get(account_token_url, headers=headers)89 account_token = account_token_result.json().get("account_token")10 return account_token # Save this in your database
Discover other Merge features in our Guides or learn more about Unified API functionality in the links below.