Fresh 2026

Authentication Flow

How a request authenticates against the Merge Unified API using your API key plus a per end-user account token.

Every Unified API call carries two credentials: your organization API key (identifies your app) and an account token (identifies which end user's Linked Account to read or write). The account token is minted when an end user connects an integration through Merge Link.

sequenceDiagram
    participant User as End User
    participant App as Your App
    participant Link as Merge Link
    participant Merge as Merge API
    participant Third as Third-Party Platform

    App->>Merge: POST /link-token (API key)
    Merge-->>App: link_token
    App->>Link: Open Merge Link (link_token)
    User->>Link: Authorize integration
    Link->>Third: OAuth / credential exchange
    Link-->>App: public_token
    App->>Merge: POST /account-token (public_token)
    Merge-->>App: account_token (store this)
    App->>Merge: GET /employees (API key + X-Account-Token)
    Merge->>Third: Normalized fetch
    Third-->>Merge: Raw data
    Merge-->>App: Common Model data

Steps

1. Create a link token. Your backend calls POST /link-token with your API key. Never expose the API key to the browser.
2. Open Merge Link. Pass the link token to the Merge Link component on the frontend. The end user picks and authorizes their integration.
3. Exchange the public token. On success Merge Link returns a public_token. Your backend swaps it for a permanent account_token via POST /account-token/{public_token}.
4. Store the account token. Persist it against the user. It is the X-Account-Token header on every future data request for that Linked Account.
5. Call the Unified API. Send Authorization: Bearer <API_KEY> and X-Account-Token: <ACCOUNT_TOKEN> on every read or write.

Headers on every request

Header	Value	Identifies
Authorization	Bearer <API_KEY>	Your application / organization
X-Account-Token	<ACCOUNT_TOKEN>	The end user's Linked Account

See the full detail in Authentication and Merge Link.