Fresh 2026

Authentication

How to authenticate: API key in the Authorization header (Bearer token) and Linked Account token in the X-Account-Token header. Includes SDK examples.

---

Overview

When making requests to the Merge API, you will need to pass proper authentication parameters so that you can identify yourself as an authorized user.

There are two primary authentication protocols we will explore below:

• Merge API key
• Linked Account tokens

The credentials you retrieve from these protocols need to be included in the headers for every request you send to the Merge API.

---

Merge API key

For any request you make when communicating with the Merge API, you will need an API key to authenticate yourself as an authorized user. You should have saved your access key after creating it in Merge, but if you no longer have it, you can regenerate your Production Access Key or create a new Remote Production or Test Access Key in API Keys in your Merge Dashboard.

If you’re writing your own requests, add your API key with a "Bearer " prefix as a header called Authorization to authorize your Merge API requests. This header must be included in every request in this format:

Authorization: Bearer YOUR_API_KEY

If you’re using the Merge SDK in your backend to communicate with Merge, you will add your API key as a parameter during your Merge client initialization.

from __future__ import print_function

import merge
from merge.client import Merge

# Swap YOUR_API_KEY below with your production key from:
# https://app.merge.dev/keys
# Swap YOUR_ACCOUNT_TOKEN with your account key from
# the linked account page.
merge_client = Merge(api_key="", account_token="")

require 'merge_hris_client'

MergeHRISClient.configure do |config|
  # Swap YOUR_API_KEY below with your production key from:
  # https://app.merge.dev/keys
  config.api_key['tokenAuth'] = 'YOUR_API_KEY'
  config.api_key_prefix['tokenAuth'] = 'Bearer'
end

import { MergeClient } from '@mergeapi/merge-node-client';

// Swap YOUR_API_KEY below with your production key from:
// https://app.merge.dev/keys
// Swap YOUR_ACCOUNT_TOKEN with your account key from
// the linked account page.
const merge = new MergeClient({
  apiKey: 'YOUR_API_KEY',
  accountToken: 'YOUR_ACCOUNT_TOKEN',
});

import com.merge.api.MergeApiClient;
import com.merge.api.resources.ats.types.Candidate;
import com.merge.api.resources.ats.candidates.requests.CandidatesRetrieveRequest;
import com.merge.api.core.RequestOptions;

public class MergeAuthentication {
    public ApiClient getApiClient() {
        // Swap YOUR_API_KEY below with your production key from:
        // https://app.merge.dev/keys
        // Swap YOUR_ACCOUNT_TOKEN with your account key from
        // the linked account page.
        MergeApiClient mergeClient = MergeApiClient.builder()
            .accountToken("ACCOUNT_TOKEN")
            .apiKey("API_KEY")
            .build();
    }
}

---

Linked Account tokens

When sending requests to the Merge API regarding your end users' data, you'll only be authorized to access or manipulate that users' data if they've gone through Merge Link and you've successfully stored their

account_token

for use with these requests.

The

account_token

also serves to signify the particular integration you wish to interact with. You can find your

account_token

at the bottom right of each Linked Account's page under the end user organization information.

Learn how to add Merge Link to your product and store your users'

account_tokens

here

and see how to use these

account_tokens

to authenticate your API requests below.

If you’re writing your own requests, add your user’s account_token as a header called X-Account-Token to authorize your Merge API requests. The account_token must be included in the headers for every request in this format:

X-Account-Token: END_USER_ACCOUNT_TOKEN

If you're using the Merge SDK in your backend to process requests related to your end users' data, you will add your user's account_token as a parameter called x_account_token to your request.

import merge
from merge.client import Merge

merge_client = Merge(api_key="", account_token="")

try:
    employee = merge_client.hris.employees.list()
except Exception as e:
    print("Exception when calling EmployeesApi->employees_list: %s" % e)

api_instance = MergeHRISClient::EmployeesApi.new
x_account_token = 'END_USER_ACCOUNT_TOKEN'

begin
  result = api_instance.employees_list(x_account_token)
  p result
rescue MergeHRISClient::ApiError => e
  puts 'Exception when calling EmployeesApi->employees_list: #{e}'
end

import { MergeClient, Merge } from '@mergeapi/merge-node-client';

const merge = new MergeClient({
  apiKey: 'YOUR_API_KEY',
  accountToken: 'YOUR_ACCOUNT_TOKEN',
});

employee = await merge.hris.employees.list()

import com.merge.api.MergeApiClient;
import com.merge.api.resources.ats.types.Candidate;
import com.merge.api.resources.ats.candidates.requests.CandidatesRetrieveRequest;
import com.merge.api.core.RequestOptions;

public class MergeAuthentication {
    public void useAccountToken() {
        MergeApiClient mergeClient = MergeApiClient.builder()
            .accountToken("ACCOUNT_TOKEN")
            .apiKey("API_KEY")
            .build();

        Candidate candidate = mergeClient.ats().candidates().retrieve(
            "", 
            CandidatesRetrieveRequest.builder()
                    .includeRemoteData(true)
                    .build(), 
            RequestOptions.builder()
                .accountToken("OVERRIDE_ACCOUNT_TOKEN")
                .build());
    }
}