Migrate integrations to Merge Unified without asking your customers to re-auth

For many teams, moving integrations to Merge is straightforward, but coordinating customer reauthorization is not. At smaller scale, reconnecting accounts requires manual cleanup. At a larger scale, support teams have to track down every customer, and some integrations never get reconnected.

Credential bootstrapping removes that step by allowing you to send Merge an existing OAuth access token and the customer's details. Merge validates the credential against the third-party platform, creates the Linked Account, and starts the initial sync. Your customer does not need to open Merge Link or authorize the connection again.

Use cases

Credential bootstrapping in Merge Unified helps you migrate your customers’ integrations more easily. Below are a few examples of what this unlocks: 

• Move existing accounts from in-house integrations or another provider without requiring customers to reconnect.
• Bulk-onboard accounts for a large customer or an acquired product through the same repeatable API workflow.
• Keep authentication inside your product. Complete the authorization flow in your interface, then send the resulting token to Merge.

How it works

Your backend sends the integration, customer details, and existing OAuth access token to POST /api/integrations/bootstrap-linked-account. Merge validates the credential with a live call to the third-party platform. A successful request creates the Linked Account, starts its initial sync, and returns a linked_account_id and account_token.

There is no link_token or public_token exchange. The linked_account.linked webhook fires as it does for an account created through Merge Link.

• Reuse the same end_user_origin_id and category, and Merge reuses the existing Linked Account instead of creating a duplicate.
• Some integrations require additional connection details, such as a domain or base URL. Call POST /api/integrations/bootstrap-linked-account/meta to retrieve the required additional_auth_fields.
• Live validation fails when a credential is expired, is missing a required scope, or is missing an additional authentication field. In that case, ask the customer to reauthorize rather than retrying the request.

Additional considerations for credential bootstrapping in Unified

Credential bootstrapping currently accepts OAuth 2.0 access tokens. Merge enables it per organization and per integration, and works with you on how credentials are stored and refreshed. Because the feature is not self-serve today, talk to your Merge account manager to confirm support for the integrations you need.

For File Storage, Chat, and Email integrations, you can still let customers choose what Merge is allowed to sync. Set require_selective_sync to true, and the Linked Account remains incomplete until the customer makes a selection in Merge Link. They see the selective sync picker, not another authorization screen.

Get started today with Merge Unified 

Product and engineering teams choose Merge Unified to save countless engineering hours building integrations, and now the experience your customers receive is more seamless than ever. Read the credential bootstrapping documentation, then talk to your Merge account manager or contact us to enable it.

‍