Magic Link

Want to start using Link without writing any code?

View our Magic Link guide to send end users a URL to authorize their integrations!

Link

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

Preview of Merge Link component

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:

  1. Get a link_token to initialize a Link session for your end user.
  2. Make Link appear in your frontend.
  3. Swap for an account_token, which authenticates future requests to the Unified API.
Diagrams associated with each step. The diagram for step 1 depicts the following: Your frontend sends a POST request for a link_token to your backend. Then your backend sends a POST request to Merge's backend for the link_token. Your backend returns the POST request from Merge's backend to your frontend. The diagram for step 2 is an example image of the Merge Link component. The diagram for step 3 depicts the following: Your frontend sends the public_token received from the Merge Link component to your backend. Then your backend makes a request to Merge's backend with the public_token to retrieve the account_token.

Step 1

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 API key as a header.

POST Request Body

Configure your Link with the following parameters:

ParameterTypeDescription
end_user_origin_idStringUnique ID for your end user.
end_user_organization_nameStringYour end user's organization.
end_user_email_addressStringYour end user's email address.
categoriesArrayThe integration categories to show in Merge Link.

["hris", "ats", "accounting", "ticketing", "crm"]
integrationOptionalStringIdentifier of third-party platform to skip Link menu for.

See Single Integration guide.

API Response

The response will include the following fields:

ParameterTypeDescription
link_tokenStringTemporary token to initialize your end user's Link.
integration_nameStringThe name of any previously connected third-party platform (otherwise null).

Pass the link_token to your frontend to display Link in step 2.

Backend - Generate Link Token
1import requests
2
3# Replace api_key with your Merge production API Key
4def create_link_token(user, api_key):
5 body = {
6 "end_user_origin_id": user.organization.id, # unique entity ID
7 "end_user_organization_name": user.organization.name, # your user's organization name
8 "end_user_email_address": user.email_address, # your user's email address
9 "categories": ["hris", "ats", "accounting", "ticketing", "crm"], # choose your category
10 }
11
12 headers = {"Authorization": f"Bearer {api_key}"}
13
14 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")
17
18 return link_token

End User Origin ID

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, and one CRM integration simultaneously.

If you want to link multiple accounts for the same user, learn more in our help center.


Step 2

Frontend – Make Link Appear

In your frontend, use the link_token from step 1 to open Link.

Display Link

Pass in two parameters:

ParameterTypeDescription
linkTokenStringInitializing token from step 1.
onSuccessFunctionCallback to handle public_token, which is returned when your end user finishes their Link session.

Pass the public_token to your backend to securely swap it for an account_token in step 3.

Frontend - Initiate Link
1import React, { useCallback } from "react";
2// In your React project folder, run:
3// npm install --save @mergeapi/react-merge-link
4import { useMergeLink } from "@mergeapi/react-merge-link";
5
6const App = () => {
7 const onSuccess = useCallback((public_token) => {
8 // Send public_token to server (Step 3)
9 }, []);
10
11 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 });
15
16 return (
17 <button disabled={!isReady} onClick={open}>
18 Preview linking experience
19 </button>
20 );
21};
22
23export default App;

Step 3

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.

Backend - Swap for Account Token
1import requests
2
3def retrieve_account_token(public_token, api_key):
4 headers = {"Authorization": f"Bearer {api_key}"}
5
6 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)
8
9 account_token = account_token_result.json().get("account_token")
10 return account_token # Save this in your database