Merge Link

Relinking

Send an end user back through Merge Link to restore a connection that stopped working

Relinking is how an end user repairs a connection that has stopped working: you create a fresh link token for the same end user and open Merge Link again. Merge marks a Linked Account as needing a relink after an end user rotates a password, an admin revokes an OAuth grant or removes a permission Merge needs, or a multi-factor session expires.

Relinking reuses the existing Linked Account. Its id, its end_user_origin_id, its integration, and the account_token you already store all stay the same, so nothing in your database has to change. Merge also keeps serving the data it synced before the connection broke, so your reads carry on working while the account waits, against data that stops updating until the relink is done.

Detect an account that needs relinking

Three signals point at the same accounts, and you can act on any of them.

SignalWhat you get
Linked Account issues webhookIssue.new with an error_description such as Invalid login credentials, Missing permission, or Expired multi-factor authentication. This is the fastest signal, since it arrives as soon as Merge classifies the failure.
GET /{category}/v1/linked-accounts?status=RELINK_NEEDEDThe affected accounts, each with a status_detail describing the failure. Surface status_detail to whoever owns the connection on your customer’s side.
A write responseA RELINK_NEEDED error. See the warnings and errors reference for the full error list.

Create a link token with the same end_user_origin_id and the same category as the existing Linked Account, then open Merge Link with it exactly as you do for a first-time connection. Passing the account’s integration slug as integration skips the integration picker and takes the end user straight to that integration’s authorization step.

Two details decide whether you repair the account or create a second one
  • Reuse the stored end_user_origin_id exactly. A different value belongs to a different end user, so Merge creates a new Linked Account instead of repairing the existing one, and you end up holding two account tokens for the same connection.
  • Create the token with the same kind of API key that created the account. A test key against a production Linked Account, or the reverse, is rejected.
$curl --request POST \
>  --url https://api.merge.dev/api/integrations/create-link-token \
>  --header 'Authorization: Bearer YOUR_API_KEY' \
>  --header 'Content-Type: application/json' \
>  --data '{
>    "end_user_origin_id": "org_a3f9b2_hris",
>    "end_user_organization_name": "Acme Corp",
>    "end_user_email_address": "[email protected]",
>    "categories": ["hris"],
>    "integration": "bamboohr"
>  }'

You can also deliver a relink as a Magic Link rather than through the embedded component, which is useful when the person who has to re-authorize is an admin who does not use your product day to day.

What happens when the end user finishes

Merge Link takes an account that is in RELINK_NEEDED straight to authorization and skips the Selective Sync and picker screens, so the end user’s existing sync selections survive the relink.

Once the end user completes the flow:

  • The Linked Account returns to COMPLETE and its syncs resume
  • Every ongoing issue on the account moves to RESOLVED, and you receive an Issue.resolved webhook for each one
  • The Linked Account linked webhook fires with "is_relink": true in data, and its payload still carries an account_token, which is the same token you already store
is_relink is true for every repeat trip through Merge Link

Any completed Linked Account that passes through Merge Link again reports is_relink as true, whether or not Merge had flagged it for relinking. Read the flag as “this is not a new connection” rather than as evidence that the connection had broken.

To learn more about the webhooks named here, see the Merge webhooks guide.