OAuth popup is blocked when connecting an integration

If the OAuth window never appears after Connect, the browser likely blocked window.open. Browsers only allow that call while the user’s click is still considered active. Anything that delays the popup until after that gesture expires can make the browser treat it as unsolicited. When this happens, you can expect an OAuthBlockedError in the onError callback of paragon.connect. Then look for work that runs between the click and window.open, so installFlow.start (or connect / installIntegration) still happens in the click handler.

Symptoms

Clicking Connect does nothing, or a spinner never ends.
Chrome or Safari shows a blocked-popup indicator.
Connect SDK onError receives:

{
  name: "OAuthBlockedError",
  message: "Popup was blocked by the browser.",
  meta: null
}

Cause

The OAuth prompt uses a popup. Chrome and Safari allow window.open when it runs in the same turn as a user gesture. They block it when the gesture has expired. The delay can come from several places. One of them is calling paragon.authenticate inside the click handler. Others include lazy-loading the SDK on click, awaiting a JWT, analytics, or a slow network after the click. A handler that stacks several of those steps looks like this:

button.onclick = async () => {
  const { paragon } = await import("@useparagon/connect");
  await paragon.authenticate(projectId, userToken);
  paragon.setHeadless(true);
  paragon.installFlow.start("salesforce", { onError, onNext, onComplete });
};

That sequence is: click, then load the SDK, then authenticate, then open OAuth. The last step is no longer attached to the click. Any one of those awaits is enough to lose the gesture.

Common scenarios	Outcome
Dynamic import of `@useparagon/connect` on click	Often blocked
`await paragon.authenticate(...)` on click (one possible cause)	Often blocked
Analytics, feature flags, or extra network calls before start	Often blocked
Slow network after click (you can reproduce this with DevTools throttling)	Often blocked

Fix

In a Headless Connect Portal, inspect error.name in onError. If it is OAuthBlockedError, this article applies. If you are using the hosted Connect Portal, check the browser’s popup indicator on your app origin.

2. Keep the Connect click free of awaits

Start the install in the click handler with no async work in front of it. If you currently authenticate on click, move paragon.authenticate to page load or app start instead. Displaying the Connect Portal already recommends that for token freshness. It also happens to keep authenticate off the click path.

// Page load, not the Connect click
await paragon.authenticate(projectId, userToken);
paragon.setHeadless(true);

// Connect click: no awaits before start
connectButton.addEventListener("click", () => {
  paragon.installFlow.start("salesforce", {
    onNext,
    onComplete,
    onError: (error) => {
      if (error.name === "OAuthBlockedError") {
        // Tell the user the popup was blocked, and that they can retry after allowing popups for your origin.
      }
    },
  });
});

Apply the same rule to other delays: load @useparagon/connect before the click, and do not await analytics or a JWT fetch before start / connect / installIntegration. Keep onNext handlers that collect pre-OAuth inputs synchronous with the next user click. Calling setPreOptions from that second click is a new gesture, so the OAuth popup that follows it is still allowed.

3. Surface the error instead of spinning

OAuthBlockedError is thrown so you can replace an infinite spinner with a retry message.

​Symptoms

​Cause

​Fix

​1. Confirm it is a popup block

​2. Keep the Connect click free of awaits

​3. Surface the error instead of spinning

​Related articles

Symptoms

Cause

Fix

1. Confirm it is a popup block

2. Keep the Connect click free of awaits

3. Surface the error instead of spinning

Related articles