> This page is for Unified. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Relinking > How to detect a Linked Account that needs re-authorization and send the end user back through Merge Link to refresh credentials, without changing the account token you already store. --- 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. | Signal | What you get | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Linked Account issues** webhook | `Issue.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_NEEDED` | The 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 response | A `RELINK_NEEDED` error. See the [warnings and errors reference](/merge-unified/writing-data/troubleshooting-writes/warnings-and-errors-reference) for the full error list. | --- ## Send the end user back through Merge Link 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`** ```bash cURL 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": "hradmin@acme.com", "categories": ["hris"], "integration": "bamboohr" }' ``` ```python import requests # linked_account is a result from GET /{category}/v1/linked-accounts def create_relink_token(api_key, linked_account): body = { "end_user_origin_id": linked_account["end_user_origin_id"], "end_user_organization_name": linked_account["end_user_organization_name"], "end_user_email_address": linked_account["end_user_email_address"], "categories": [linked_account["category"]], # Skip the picker and open this account's own integration "integration": linked_account["integration"]["slug"], } response = requests.post( "https://api.merge.dev/api/integrations/create-link-token", json=body, headers={"Authorization": f"Bearer {api_key}"}, ) return response.json()["link_token"] ``` You can also deliver a relink as a [Magic Link](/merge-unified/merge-link/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](/merge-unified/reading-data/webhooks/merge-webhooks) guide.