alterConnect.open()

open() takes an OAuth Connect session token minted on the application backend and attempts to open the Alter-hosted UI. Desktop popup results are routed through callbacks.

await alterConnect.open({
  token: sessionToken,
  onSuccess: (grants, completion) => {
    console.log("connected", grants);
    console.log("not retained", completion.failedGrants);
  },
  onError: (error) => console.error(error),
  onExit: () => console.log("user cancelled"),
  onEvent: (eventName, metadata) => console.log(eventName, metadata),
});

Signature

alterConnect.open(options: OpenOptions): Promise<void>

The returned promise resolves after the launch attempt — not when the user finishes the flow. A blocked popup still counts as an attempt: onError receives popup_blocked, onEvent receives connect_opened, and the promise resolves unless onEvent itself throws. See OpenOptions for the full type.

Parameters

Name	Type	Required	Description
options.token	string	yes	Session token minted by the application backend with app.createConnectSession(). Short-lived (10-minute default).
options.onSuccess	(grants: Grant[], completion: ConnectCompletion) => void	yes	Fired when the popup flow completes with at least one retained grant. The first argument is the grants array. completion.failedGrants reports providers whose grants could not be retained after selected usage limits failed to apply.
options.onError	(error: AlterError) => void	no	Fired for failures delivered to the browser SDK, such as a blocked popup, redirect-state failure, malformed result, server-posted callback error, or total usage-limit application failure.
options.onExit	() => void	no	Fired when the user closes the popup without finishing.
options.onEvent	(eventName: string, metadata: Record<string, unknown>) => void	no	Fired for analytics. See Events & callbacks for the exact event the SDK emits today.

onSuccess is the only required callback. Surfacing onError is strongly recommended, especially for popup-blocked and malformed-result failures.

Launch-time rejections

Because open() is async, these conditions reject its returned promise before a launch attempt:

Condition	Error code
The SDK instance was already destroy()-ed.	sdk_destroyed
token is missing or not a string.	invalid_options
onSuccess is missing or not a function.	invalid_options

Failures that reach the browser SDK are routed through onError. onSuccess, onError, and onExit run through the event emitter’s exception guard. If one throws, the SDK logs the exception rather than converting it into AlterError, and that callback’s final state/listener cleanup does not run. Keep these callbacks non-throwing. onEvent is invoked directly; if it throws, the already-launched open() call rejects.

Invalid or expired tokens detected while binding or loading the hosted page are rendered inside that page; they are not reliable onError callbacks. A provider authorization denial also returns to the hosted provider picker so another provider can be selected. Use backend session polling for terminal-state recovery that must not depend on popup messaging.

Desktop popup flow

On desktop, open() launches a centered 500×700 px popup that loads the Alter Connect UI. The popup communicates back via postMessage; the SDK validates the origin against the configured Alter host before accepting any message.

For a validated success or error message, the flow handler closes the popup before invoking the application callback. If that callback returns normally, the SDK then resets its open-state flag, removes per-open listeners, and emits close.

If the browser blocks the popup, onError fires with code: "popup_blocked". Fetch the session before the click so open() can run directly inside the user gesture.

const token = await fetchToken();
button.disabled = false;

button.addEventListener("click", () => {
  void alterConnect.open({ token, onSuccess, onError });
});

Closing the popup without finishing invokes onExit locally. It does not mark the backend session denied, so backend polling remains pending until its own timeout or the session expires.

Mobile redirect flow

Note

The device classifier uses a full-page redirect for mobile-classified viewports up to 480 px wide and for mobile-classified 481–1024 px viewports in portrait. Other devices use the popup flow.

On the redirect branch, the SDK:

1. Saves the current page URL and a timestamp in sessionStorage.
2. Navigates the entire page to the Connect UI URL.
3. Leaves the original JavaScript context, including per-open callbacks and event listeners.

Warning

The callbacks passed to this open() call do not survive the navigation. Set returnUrl when creating the session; the flow then navigates back with the outcome. On the returning page, construct AlterConnect and attach .on("success", ...) / .on("error", ...) listeners; the SDK retains the outcome until the matching first listener attaches. Per-open onSuccess / onError callbacks are not a redirect-return delivery mechanism. Use createConnectSession() plus pollConnectSession() on the application backend for sessions created without a returnUrl.

The returning page load is verified before any callback runs: the SDK mints a per-flow value that is echoed on the return, and callback parameters that do not carry it are ignored, so a hand-crafted link cannot fake a completion. Return state is accepted for at most five minutes and older state is removed silently — past that window, completion is recoverable only by polling the session from the application backend.

A session that authorized several providers returns with the first grant only, because the outcome is reconstructed from a URL. Poll the session to retrieve the full set, including any provider that failed.

Multiple providers in one session

onSuccess receives an array of grants because a session can authorize multiple providers before confirmation. When the session retains one provider grant, the array has length 1.

await alterConnect.open({
  token: sessionToken,
  onSuccess: (grants, completion) => {
    for (const grant of grants) {
      console.log(grant.provider, grant.grant_id);
    }
    for (const failure of completion.failedGrants) {
      console.warn(failure.providerId, failure.reason);
    }
  },
});

If every authorized grant is revoked because selected usage limits could not be applied, onSuccess does not fire. onError receives code: "grant_policy_application_failed" and a typed failedGrants array.

See the Grant, ConnectCompletion, and ConnectFailedGrant references.

Recovery and approval rules

Recovery is configured when the application backend mints the session. A session returned by createConnectSessionForError() is opened with the same token option as any other Connect session. @alter-ai/connect exports none of the server-side exception classes, including ReAuthRequiredError, NoDelegatedGrantError, GrantNotFoundError, CredentialRevokedError, or the headless-flow ConnectFlowError family (ConnectDeniedError, ConnectConfigError, ConnectTimeoutError).

allowUserPolicyRules defaults to enabled during session creation. It lets the hosted UI add narrowing deny, human-approval, time-window, quota, and operation/parameter content rules. A human-approval rule gates later API calls; Connect authors the rule but does not run the later approval workflow. Session-level grant-expiry bounds separately add a constrained duration picker to the hosted confirmation screen. These are session-creation options, not OpenOptions.

Backend session creation

The session token passed to open() is minted on the application backend, never in the browser. Provider allowlists, per-provider requested scopes, origin binding, user identity, recovery context, delegated agents, onward-delegation permission, account switching, requested sibling grants, delegation scope constraints, grant-expiry bounds, and user-authored policy rules are all configured there; open() accepts only the five fields listed on this page.

See Embed the Connect widget and the server SDK references for session creation and polling.