SDK Release Notes

• Fixed installFlow.cancel() not properly stopping the underlying session polling when cancelling an active OAuth flow.

• Updated TypeScript types for paragon.getUser so that resources[*].providerData is now typed and accessible.

• Fixed concurrent paragon.request proxy GET calls to the same URL failing with a “body stream already read” error.
• Fixed error propagation in the Connect OAuth popup for Custom Integrations when credential values are empty.

• Added functions for retrieving available triggers in ActionKit and listing required parameters for rendering with the Headless Connect Portal.

• Fixed requested browser permissions so that copy-to-clipboard inputs correctly write to the user’s clipboard.

• Recategorized React as a peer dependency in the Connect SDK to enable better compatibility with React 18+ applications.
• Updated types for paragon.request, so requestOptions properties can be omitted when not needed, improving TypeScript ergonomics.

• Fixed persona metadata key normalization improving SDK efficiency.

• Fixed Custom Integration identifier handling so the SDK now uses the slug returned by the API instead of recomputing one from the integration display name.

• Added paragon.setDataSources API for centralized configuration of data sources for Custom Dropdowns and Field Mapping inputs in the Headless Connect Portal.
• Added paragon.getSourcesForInput resolver to retrieve typed source configurations for inputs, enabling more predictable data source handling with typed discriminators (SingleSource, FieldMapperSources, ComboSources, DefaultFieldValueSources).

• Added support for handling streamed responses in paragon.request proxy requests, enabling proper handling of large file downloads (e.g., from Google Drive).

• Added externalId option to paragon.connect and paragon.installIntegration for associating credentials with an external identifier. The externalId is also available on credential objects returned by paragon.getUser.

• Fixed handling of non-ASCII characters in user metadata passed to paragon.authenticate. The SDK now properly encodes metadata values, ensuring characters like Unicode text are fully supported.

• Added refreshOnOpen option for custom dropdowns, enabling dropdown values to reload each time the dropdown is opened. This supports dependent dropdown patterns where one dropdown’s options change based on another input’s value.

• Fixed Box integration file picker’s global CSS styles from leaking into and conflicting with the host application’s styles.
• Fixed misleading error message when calling paragon.updateWorkflowUserSettings for workflows that are not deployed.

• Fixed an issue where the SDK could send the initial request to the wrong server endpoint when restoring state from localStorage before configureGlobal() was called, causing unnecessary requests and errors for customers using custom or on-prem endpoints.

• Increases the timeout for OAuth connections to complete from 1 minute to 3 minutes.

• Fixes an issue where the onComplete callback toparagon.installFlow.start was not always providing the credential details for the account that was connected.

• Updates the type signature for picker.init() to optionally accept a developerKey property (required for Google Drive only).
• Updates the type signature for paragon.connect to accept Custom Dropdowns loader functions.
• Adds support for Multi-Account Authorization to paragon.getFieldOptions.

• Fixes an issue that caused stale state to be returned from paragon.getUser after calling paragon.updateIntegrationUserSettings or paragon.updateWorkflowUserSettings.

• Adds a new InstructionStage to the Headless Connect Portal to render instructional text as required by integration install flows (such as Salesforce package installation).

• Fixes an issue that prevented Dynamic Field Mapping from rendering properly in the headful Connect Portal.

• Adds support for Shared Drives in the Google Drive File Picker as a tab in the picker. You can enable this with the following options:
  const picker = new paragon.ExternalFilePicker("googledrive", {
    integrationOptions: {
      googledrive: {
        enableSharedDrives: true
      }
    }
  });
  
• Adds support for allowMultipleCredentials, overrideRedirectUrl, and selectedCredentialId install options to the Headless Connect Portal InstallFlow.
  • Note: In previous versions, Multi-Account Authorization was automatically enabled for the Headless Connect Portal. The allowMultipleCredentials: true option must now be passed to opt-in to Multi-Account Authorization for consistency with other SDK functions.

• Updates Google Drive File Picker MIME type filtering by using the setSelectableMimeTypes option in the Google Picker SDK. This change means that all files will appear in the view, but only MIME types passed in allowedTypes array will be selectable (mirroring the behavior of other file pickers).
• Adds a new function paragon.getCustomWebhookUserManualUrl for constructing the URL of user-level Custom Webhooks. This function can be used to prompt your user to register a Custom Webhook URL in their integration account settings.

• Fixes the base URL used for the Proxy API when using the SDK for on-prem environments.

• Improves the security of OAuth connection flows.

• Fixes a compatibility issue between the SDK using certain Redux libraries by preventing returning internally-managed state in SDK responses.

• Updates the base URL used for triggering App Events and Workflows from the SDK to the newest service URL.
• Fixes an issue where X-Paragon-Credential was included in outgoing HTTP headers when not explicitly set by the SDK.

• Adds paragon.installFlow.cancel to the Headless Connect Portal API to cancel in-progress installs. Learn more

• Fixes an issue where onSuccess callbacks would not fire for some types of integrations.
• Fixes types for paragon.request to include selectedCredentialId for Multi-Account Auth.
• Fixes an issue where credentials with a non-VALID status could not be uninstalled with paragon.uninstallIntegration.

• Adds support for the user-configured-oauth authentication type for the Headless Connect Portal.

• Fixes types for paragon.installIntegration to include selectedCredentialId in available options.
• Fixes connection issues for the Headless Connect Portal for certain integrations that have a PreOptionsStage, like Zendesk.

• Adds support for oauthTimeout option to the paragon.installFlow.start method of the Headless Connect Portal, to specify the number of milliseconds to wait for the OAuth prompt to complete.
• Adds OAuthBlockedError and OAuthTimeoutError as possible error types for paragon.installFlow.start to detect when the OAuth prompt is blocked by the browser or takes longer than expected.

• Adds a centralized onError callback for the paragon.installFlow.start method of the Headless Connect Portal.

• Fixes types for paragon.connect to include definitions for Custom Dropdowns.
• Fixes an issue where Multi-Account Authorization could not be used with the Headless Connect Portal.

• Fixes an issue where Multi-Config could not be used correctly when sending App Events with the SDK.

• Adds support for Multi-Account Authorization for File Pickers.

​

New: Field Mapping for all integrations

• Updates paragon.request method to use the new URL changes introduced in the 2025-07 API release.

• Fixes an issue where the Headless Connect Portal might not progress to the post-OAuth stage when the OAuth prompt is completed.

• Adds support for Box File Picker.

• Fixes an issue where showPortalAfterInstall option in paragon.installIntegration did not correctly prompt the Connect Portal after install.
• Fixes an issue where the Headless Connect Portal (using paragon.installIntegration) intermittently did not show post-OAuth options (such as SharePoint site selection) after the OAuth prompt was completed.

• Exposes new CredentialStatus and IntegrationMetadata types from the SDK.

• Removes call to /sdk/projects to improve performance of SDK authentication.

• Updates return types of Headless Connect Portal function paragon.getDataSourceOptions to show all available fields for input sources.

• Updates paragon.getFieldOptions function to make parameters field optional.

​

New: Headless Connect Portal improvements

​

Breaking changes

• There are no breaking changes in this release. If you are using the Headless Connect Portal in v1.x of the SDK, all existing functionality with paragon.installIntegration will be preserved.
• To opt-in to improvements to the Headless Connect Portal that can utilize more of your own UI components, see our migration guide below.

​

Migrating from v1 of the Headless Connect Portal

1. Call paragon.setHeadless in your implementation to opt in to the new version of the Headless Connect Portal:
   paragon.setHeadless(true);
   
2. Implement all stages of the authentication flow described in the Headless Connect Portal docs. In v1.x of the SDK, the following stages were handled by the headful Connect Portal appearing and should now be implemented by your own components:
   • Account Type selection (e.g. Salesforce Production vs. Salesforce Sandbox) — AccountTypeStage
   • Pre-OAuth / API Key inputs (e.g. Stripe API Key input, Shopify Store URL) — PreOptionsStage
   • Post-OAuth inputs (e.g. Atlassian site, SharePoint site selection) — PostOptionsStage
   • To implement the above stages, replace paragon.installIntegration with paragon.installFlow.start (this function will guide you through the above install stages):
   Migrating to installFlow

   paragon.installIntegration("salesforce"); 
   paragon.installFlow.start("salesforce", { 
       // Handle all stages of the install flow
   });