Bootstrap

Bootstrapping creates a Linked Account from credentials you already hold, so your end user never sees an authorization screen. You send Merge the credentials and the end user’s details, Merge validates them against the third-party platform, and the account completes and starts syncing.

Use it when the authorization already happened somewhere else:

• Migrating in-house integrations to Merge, where you hold the credentials and don’t want to ask every customer to reconnect
• Moving off another integration provider, where you can export credentials and hand them over in one pass
• Onboarding an end user without Link, where you control the connection experience in your own product

Bootstrapping is enabled per organization and per integration, and Merge sets up how credentials are held and refreshed with you at the same time. Contact Merge to turn it on and to confirm the integrations you need. Coverage today spans File Storage, Chat, Ticketing, Knowledge Base, CRM, Email, and Calendar, and not every integration within a category is enabled.

How it works

Your backend posts the credentials to /integrations/bootstrap-linked-account with your API key. Merge validates them with a live call to the third-party platform, then creates the Linked Account and starts the initial sync. There is no link_token and no public_token exchange, so the account token comes back in the response and the linked_account.linked webhook fires just as it does for an account created through Link.

Because validation is live, a call fails when the credentials are expired or missing a scope. Treat a failure as a signal to re-authorize that end user rather than to retry.

$
curl --request POST \
>
  --url https://api.merge.dev/api/integrations/bootstrap-linked-account \
>
  --header 'Authorization: Bearer YOUR_API_KEY' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
    "integration": "jira",
>
    "category": "ticketing",
>
    "end_user_origin_id": "customer_abc",
>
    "end_user_email_address": "[email protected]",
>
    "end_user_organization_name": "Acme",
>
    "linked_account_credentials": {
>
      "oauth_access_token": "YOUR_END_USER_ACCESS_TOKEN"
>
    },
>
    "additional_auth_fields": {
>
      "base-url": "https://acme.atlassian.net"
>
    }
>
  }'

A successful call returns 201 with linked_account_id and account_token. Store the account token against your end user the same way you would after a Link session.

Request parameters

To find out what an integration expects in additional_auth_fields, post the same integration and category to /integrations/bootstrap-linked-account/meta. The response names each required field with its type and a description, and an empty response means the integration needs credentials only.

Letting your end user choose what to sync

Some end users need to pick which files, channels, or mailboxes Merge can access even when you hold their credentials. Set require_selective_sync to true and the account is created but left incomplete, so nothing syncs until the selection is made.

To collect it, create a link token with completed_account_initial_screen set to SELECTIVE_SYNC and open Merge Link as usual. Your end user lands on the picker instead of an authorization screen, and the account completes when they submit. This is available for File Storage, Chat, and Email.

Failures

A call that fails validation returns 400 with the reason in non_field_errors, and the third-party platform’s raw response in raw_api_response where it gave one. The usual causes are an expired token, a missing scope, or a missing entry in additional_auth_fields. A 400 reading Integration and admin level not supported means the integration is not enabled for your organization yet.

Calling bootstrap again for an end_user_origin_id that already has a Linked Account reuses that account rather than creating a second one.

Next steps