How should a B2B SaaS product design integrations: connect, sync, errors and disconnect?

Illustrative situation: the revenue operations lead at a customer wants the product connected to her company’s CRM. She finds an Integrations page with a logo grid and a Connect button. She clicks it and the CRM answers “Approval required”. Nothing in the product tells her who can approve, so she writes to support. Once an admin approves, the first sync starts, but nobody showed her which fields go where, so about 9,800 contacts land in the wrong columns. Seventy days later the CRM admin leaves, the access ends, and the sync stops without a word. She learns about it when a report looks stale. The scene is invented, but the pattern is common: the team built a connection and never designed what happens after it.

Humbleteam, a digital product design agency, publishes this guide. It treats an integration as a list of states, such as pending approval, syncing, partly synced, expired and disconnected. For each state it asks what the customer sees, what they can do and who hears about it. A state map near the end collects the answers so a team can copy it. Vendor behavior below is described as of October 28, 2026 and can change.

What should the directory show before anyone clicks Connect?

Put the facts a cautious admin needs on each directory card. HubSpot’s marketplace listing is a useful model. It shows who built the app, how many accounts have installed it, the plan and user permissions required, and a “Shared data” section. That section says how data syncs and uses one arrow for one direction and two arrows for both.

Our suggestion for a card in your own product:

• Name the direction of data: what comes in, what goes out, and whether anything is deleted.
• Say who can connect it, in plain words, before the click.
• Show one of four states on every card: not connected, pending approval, connected, needs attention.
• Put a “needs attention” integration at the top of the page, not in alphabetical order.

What does someone see when they are not allowed to connect?

Most B2B customers have approval rules, so the blocked path is a main path. Four platforms handle it differently.

HubSpot says installing an app takes a Super Admin or a user with Marketplace access. Someone without that permission can use “Request to install”, choose an administrator, and send an email that names the app and the permissions it needs.

Slack lets owners turn on app approval. Members can then request apps, and by default requests go to Workspace Owners, who can appoint app managers. Slack’s help page adds a detail worth copying: approving a request means approving the scopes the app will use. If an owner restricts an app that is already installed, members can keep using it until it is uninstalled.

Microsoft Entra shows an “Approval required” window when user consent is off and the admin consent workflow is on. The user types a justification and selects “Request approval”. Then a “Request sent” message appears, and an email follows when the request is approved, denied or blocked. Microsoft’s overview also notes that if someone sends several requests, only the first reaches the admin.

Salesforce has the opposite trap. Its Permitted Users setting defaults to letting any user authorize a connected app. Switching to “Admin approved users are pre-authorized” removes access for current users unless their profile or permission set authorizes the app.

For your own product, the blocked screen should name the person or role who can approve, offer to send the request from inside the product, and show the request’s status on the directory card afterward. Who may connect is a permission like any other, and our guide to roles and permissions covers how to build that model.

How do you explain what the integration can do?

A consent screen lists scopes, which are the permissions the integration asks for. Customers read them as risk. Three published rules shape what to ask for and how to explain it.

First, ask for less. Slack’s Marketplace guidelines say the less access an app requests, the more comfortable users feel installing it. They also ask developers to explain how the app uses each scope, not what the scope does. Slack’s OAuth guide warns that scopes add up across installs and cannot be removed from a token without revoking it.

Second, ask in context. Google’s best practices say not to request data at first sign-in unless it is essential. Request the scope when the person picks the feature that needs it. If they decline, disable that feature and explain how to ask again.

Third, expect partial consent. Google’s granular permissions guide says users can approve some requested scopes and not others, so the app must check what was granted. Slack’s optional scopes work the same way, and Slack tells apps to store the granted scopes and hide the features they no longer allow. HubSpot’s optional scopes are dropped from the request when the chosen account lacks the tool, so the app must read the token to see what it got.

HubSpot’s OAuth documentation says an access token reflects the scopes requested, not the connecting user’s own limits. A rep who can see only their own contacts and authorizes a contacts scope produces a token that can view all contacts. Tell the connecting person that the integration may see more than they can.

If your integration touches Google data, plan the timeline. Google’s unverified apps page says an app using sensitive or restricted scopes without verification shows an “unverified app” screen and is limited to 100 new users. Verification can take several months depending on the data requested. Its verification help center adds that an app name and logo appear on the consent screen only after brand verification.

What happens between consent and the first sync?

Send the person somewhere meaningful when the OAuth screen closes. Slack’s guide says the user deserves to know the end of the story, whether the app installed or failed. A bare redirect to the dashboard does not do that.

Then show the mapping before anything moves. HubSpot’s field mapping page is a clear reference. Each mapping has a sync rule: prefer Salesforce unless blank, always use Salesforce, two-way, or don’t sync. It requires compatible field types, such as a dropdown to a picklist. Its notes carry two warnings that belong on the screen. Existing values in a newly created mapping do not sync retroactively. And when a record has no sync history for a field, the first sync takes the current Salesforce value as the baseline, which can overwrite a more recent HubSpot value.

Merge, a unified API vendor, splits mappings in two: some apply to every connected account of an integration, others to one customer’s account, for fields specific to that customer. That split is a good test of your own design. Decide which mappings your team owns and which the customer sets.

Our suggestions for the screen:

• Show direction per field as an arrow, with the rule in words: “CRM wins when both have a value”.
• Preview 10 to 25 real records, source value beside result.
• Warn before the first sync if it will overwrite existing values, with a count.
• Start the sync with an explicit button, and say whether it continues if the person leaves the page.

A one-off file upload has its own recovery problems, covered in our guide to import error recovery. An integration differs because it keeps running after the person has left.

What should sync status and history show?

A green dot says little. HubSpot’s Salesforce integration shows a Sync Health tab with API use over the last 24 hours and one card per error type, each with a count of errors and affected records. The admin can open a temporary view of those records, fix them, select the resolved errors, and click Resync. Errors export to CSV, and notifications can go out instantly, daily or weekly.

Merge publishes a vocabulary worth borrowing. Its sync statuses are Syncing, Done, Partially Synced, Failed, Paused and Disabled. Paused means no inbound request for over 2 weeks, or failed syncs for over 2 weeks.

Zapier’s replay documentation shows another idea: retry only what failed. If a Zap sends an email and then fails to add a spreadsheet row, replay skips the trigger and the email and tries the row again. Your own retry button can carry the same reassurance: “Retry 160 failed records. The 9,640 that synced are not touched.”

Our suggestions:

• Lead with the time of the last successful sync and, if known, the next one.
• Show counts in, out and failed for the latest run, per object.
• Keep a run history with a status, a start time and a count you can click.
• Split “needs you” from “will retry on its own”. They deserve different colors and different emails.

How should each error state read?

Four errors are certain to appear.

Expired token. Tokens end for many reasons. Google’s OAuth documentation lists a refresh token unused for six months, a revoked grant, an admin restricting the service, and a project in “Testing” status, which issues a refresh token that expires in 7 days. It also caps refresh tokens at 100 per Google Account per client, and the oldest stops working without warning. Salesforce lets admins set the policy: valid until revoked, expire after n days unused, or expire immediately. With token rotation turned on, Slack access tokens expire every 12 hours, so a failed refresh is the event to handle. The customer should see the cause when you know it, not “authentication failed”.

Revoked access. The other tool’s admin can end the connection without telling you. Slack sends tokens_revoked and app_uninstalled events to apps that subscribe. Stripe sends account.application.deauthorized when a user disconnects a platform. Zapier’s troubleshooting page for its Agents product lists a changed password, an app revoking access for inactivity, missing permission, and an unshared connection. Show “Disconnected from the CRM” as its own state, different from “expired”, because the fix may be a conversation with another person.

Rate limits. This is the one error the customer cannot fix. Slack returns HTTP 429 with a Retry-After header, and it applies limits per method, per workspace, per app. HubSpot limits each account that installs a marketplace app to 110 requests per 10 seconds. Show a calm message such as “Catching up, expected by 3:40 PM” and escalate only if it persists.

Partial sync. Merge defines Partially Synced as one or more fields failing while others succeed, and says a likely cause is a missing permission. HubSpot groups failures by cause, such as associations, duplicates, custom code and permissions, and gives a fix for each. Show the failed records and the reason for each, and let the person retry only those.

For wording, NN/g’s error-message guidelines ask for plain language, a precise description, constructive advice, and no blame. “Invalid token” fails all four. A message like “Your CRM ended our access on October 12. Reconnect to resume syncing” passes.

Timing matters too. Zapier’s replay page says it retries a failed step up to 5 times and sends no error email until the last attempt fails. Its developer documentation says a Zap is paused automatically when 95 percent of its runs in the last 7 days errored. Merge advises showing the failure detail to whoever owns the connection on the customer’s side. Tell the connection owner first and the admins later.

How should reconnect work?

Reconnect should repair the connection, not rebuild it. Merge’s relinking guide is explicit: the account id, the stored token and the integration stay the same, and Merge keeps serving the data it synced before the break. Its relink screen goes straight to authorization and skips the selective-sync and picker screens, so earlier selections survive. HubSpot says in its uninstall guidance that uninstalling and reinstalling is not recommended as a fix for sync errors.

Our suggestions:

• Reconnect keeps the mappings, filters and history. Say so on the button’s screen.
• Show which account is connected now, and ask before replacing it if the person signs in with a different one. Merge’s guide shows why the check matters: relinking under a different end-user ID creates a second connection instead of repairing the first.
• Open the authorization step directly, as Merge does.
• After success, show “Catching up from October 12” and then the result of the catch-up run.
• If the consent screen now asks for more scopes than before, say which ones are new.

What happens to data when someone disconnects?

Decide this before building the button, because it is a data policy as much as a screen. HubSpot’s disconnect dialog for Salesforce is the clearest published example. It lists what is removed (integration settings, field mappings, custom object syncs) and what stays (the contacts, companies, deals and tasks created from Salesforce records, plus the property values added by mappings). Workflow actions that relate to Salesforce stay but no longer run. The user types “uninstall” to confirm, and then an email asks them to reassign records owned by users who existed only in Salesforce.

Stripe’s OAuth reference shows the other side: after a platform’s access is revoked, the platform can no longer reach the account, but the account keeps its own data in its Dashboard. Slack’s Marketplace guidelines require a privacy policy that says how long data is kept and how a person can request deletion.

NN/g’s confirmation dialog guidance fits here. It asks for specifics about consequences, not “Are you sure?”, and for a typed word only on rare, dangerous actions.

Our suggestion is a disconnect panel with three lists:

• Stops now: syncing, workflows that use the integration, notifications.
• Stays in your product: records that came from the other tool, marked as no longer updating.
• Removed, and when: anything you delete, with the date and a way to export first.

Offer a choice where the answer differs by customer: keep synced records, or remove them after 30 days. The 30 days is only an example. Write the same facts into the email sent to admins, and record who disconnected it.

Illustrative worked example: a contract product connects to a CRM

Everything here is invented. A fictional B2B product for legal teams lets customers connect their CRM so contract status shows beside each deal.

The revenue operations lead clicks Connect. She is not a CRM admin, so the CRM shows its approval request. The product catches this and shows: “Your CRM needs an admin to approve this. Send a request to your CRM admin?” She sends it, and the card shows “Waiting for approval, sent today”.

After approval, she lands on a mapping screen with six fields. Contact email maps both ways, deal stage maps one way, and deal owner is flagged: “Owners must match exactly. 14 of 212 do not.” A preview shows 20 records. A warning reads: “This will overwrite 1,140 existing contact phone numbers with CRM values.” She changes that field to “don’t sync”, then starts the sync.

The first run reports 9,640 of 9,800 contacts synced, and the status is “Partly synced”. The other 160 contacts are listed, each with a reason: missing email. She downloads the list and fixes it in the CRM. “Retry failed only” moves the 160 across.

On day 71, the CRM admin who approved the integration leaves, and that admin’s access ends. The state changes to “Disconnected from the CRM, October 12”. The connection owner gets an email the same day, saying what stopped, the last good sync time and a Reconnect button. Admins get a shorter email 3 days later if nothing changed. Reports show “Updated October 12” in the header.

Reconnect opens the CRM sign-in directly. A new admin signs in. The screen asks: “This is a different CRM account. Replace the connected account?” The mappings stay. The product reports “Catching up from October 12: 2,300 changes”, and then “Caught up”.

Months later, someone chooses Disconnect. The panel states that syncing stops now, that the 9,800 contacts and their contract status stay in the product labeled “no longer updating”, and that nothing is removed in the CRM. She types the integration’s name to confirm. Admins are told who did it and when.

Where do these defaults stop working?

The sources here are vendor documentation and well-known UX research. They show how platforms behave, not how your customers will. No study of integration screens in B2B products was found, and none is claimed. Vendor behavior changes. For instance, Salesforce’s help page said as of October 28, 2026 that creating new connected apps is restricted as of Spring ’26 and recommends external client apps. This guide leaves out outbound webhooks, API-key connections, embedded workflow tools, marketplace review timelines and security certification.

What can you produce now?

Four things, before anyone draws a screen:

1. A consent inventory: every scope you ask for, in plain words, with a reason and what stops working if declined.
2. A mapping sheet: each field, its direction, its rule when both sides have a value, and the first-sync behavior.
3. The state map above, filled in for your first integration, with draft copy for each state and each email.
4. A test list: a non-admin trying to connect, a declined scope, a partial sync, an expired token, a revoked grant, a rate limit, a reconnect with a different account and a disconnect.

If you plan to bring in outside designers, ask each team to fill in the state map for two of your states and to explain the disconnect panel. Our comparison of UX/UI agencies that design complex B2B SaaS platforms shows which studios publish work on screens like these.