Merge Docs

Authentication

Learn how to authenticate your requests to the Merge API.

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:

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. In the Merge app, you can find your credentials in API Keys under Configuration.

API Keys preview

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.

Merge SDK - Client Initialization
Python
Ruby
Node
Java
from __future__ import print_function

import time
import MergeHRISClient

configuration = MergeHRISClient.Configuration()

# Swap YOUR_API_KEY below with your production key from:
# https://app.merge.dev/configuration/keys
configuration.api_key['tokenAuth'] = 'YOUR_API_KEY'
configuration.api_key_prefix['tokenAuth'] = 'Bearer'

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.

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.

Preview of Merge Link component

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.

Merge SDK - Use Account Token
Python
Ruby
Node
Java
with MergeHRISClient.ApiClient(configuration) as api_client:
    api_instance = MergeHRISClient.EmployeesApi(api_client)
    x_account_token = 'END_USER_ACCOUNT_TOKEN'

    try:
        api_response = api_instance.employees_list(x_account_token)
        pprint(api_response)
    except MergeHRISClient.ApiException as e:
        print('Exception when calling EmployeesApi->employees_list: %s' % e)