> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useparagon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Release Notes

> Release notes for new versions of the Paragon SDK.

### Updating to the latest version

To update your SDK to the latest version, run the following commands in your app or codebase referencing the SDK:

```bash theme={null}
npm install @useparagon/connect@latest
```

## Release Notes

<Update label="v2.4.0">
  **Improvements:**

  * Added functions for retrieving available triggers in ActionKit and listing required parameters for rendering with the [Headless Connect Portal](/connect-portal/headless-connect-portal).

  **Fixes:**

  * Fixed requested browser permissions so that copy-to-clipboard inputs correctly write to the user's clipboard.
</Update>

<Update label="v2.3.2">
  **Improvements:**

  * Recategorized `React` as a peer dependency in the Connect SDK to enable better compatibility with React 18+ applications.
  * Updated types for [`paragon.request()`](/apis/api-reference#request-integrationtype-string-path-string-requestoptions-requestinit-→-promise), so `requestOptions` properties can be omitted when not needed, improving TypeScript ergonomics.

  **Fixes:**

  * Fixed persona metadata key normalization improving SDK efficiency.
</Update>

<Update label="v2.3.1">
  **Fixes:**

  * 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.

  <Info>
    **Custom Integration identifiers are now immutable**

    Before API version [2026-04](/changelog/api#2026-04), changing the display name of a Custom Integration would result in a change in the integration identifier/slug (used in `paragon.connect`) and the integration source path (after a `para pull`).

    This identifier is now immutable and set at the time your Custom Integration is created.

    For existing Custom Integrations, the identifier is set immutably to the same value it currently has in your project. SDK versions \< 2.3.1 will continue to use name-derived identifiers and work without issue. You can upgrade to v2.3.1 or later to use the current, immutable identifiers.

    Learn more about these changes in the [API Changelog](/changelog/api#2026-04).
  </Info>
</Update>

<Update label="v2.3.0">
  **Improvements:**

  * Added [`setDataSources()`](/apis/api-reference#setdatasources) API for centralized configuration of data sources for [Custom Dropdowns](/connect-portal/workflow-user-settings/custom-dropdowns) and [Field Mapping](/connect-portal/field-mapping) inputs in the Headless Connect Portal.
  * Added [`getSourcesForInput()`](/apis/api-reference#getsourcesforinput) resolver to retrieve typed source configurations for inputs, enabling more predictable data source handling with typed discriminators (`SingleSource`, `FieldMapperSources`, `ComboSources`, `DefaultFieldValueSources`).
</Update>

<Update label="v2.2.9">
  **Improvements:**

  * Added support for handling streamed responses in [`paragon.request()`](/apis/api-reference#request) proxy requests, enabling proper handling of large file downloads (e.g., from Google Drive).
</Update>

<Update label="v2.2.8">
  **Improvements:**

  * Added `externalId` option to [`connect()`](/apis/api-reference#connect) and [`installIntegration()`](/apis/api-reference#installintegration) for associating credentials with an external identifier. The `externalId` is also available on credential objects returned by [`getUser()`](/apis/api-reference#getuser).

  **Fixes:**

  * 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.
</Update>

<Update label="v2.2.7">
  **Improvements:**

  * 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.

  **Fixes:**

  * 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 `updateWorkflowUserSettings` for workflows that are not deployed.
</Update>

<Update label="v2.2.6">
  **Fixes:**

  * 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.
</Update>

<Update label="v2.2.5">
  **Improvements:**

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

  **Fixes:**

  * Fixes an issue where the `onComplete` callback to`paragon.installFlow.start()` was not always providing the credential details for the account that was connected.
</Update>

<Update label="v2.2.4">
  **Improvements:**

  * 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](/connect-portal/workflow-user-settings/custom-dropdowns) loader functions.
  * Adds support for [Multi-Account Authorization](/apis/api-reference/multi-account-authorization) to `paragon.getFieldOptions()`.

  **Fixes:**

  * Fixes an issue that caused stale state to be returned from `paragon.getUser()` after calling `updateIntegrationUserSettings` or `updateWorkflowUserSettings`.
</Update>

<Update label="v2.2.3">
  **Improvements:**

  * Adds a new `InstructionStage` to the [Headless Connect Portal](/connect-portal/headless-connect-portal) to render instructional text as required by integration install flows (such as Salesforce package installation).

  **Fixes:**

  * Fixes an issue that prevented Dynamic Field Mapping from rendering propertly in the headful Connect Portal.
</Update>

<Update label="v2.2.2">
  **Improvements:**

  * Adds support for Shared Drives in the [Google Drive File Picker](/resources/integrations/google-drive#using-the-google-drive-file-picker) as a tab in the picker. You can enable this with the following options:

    ```js theme={null}
    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`](/apis/api-reference#installflow).
    * **Note**: In previous versions, [Multi-Account Authorization](/apis/api-reference/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.
</Update>

<Update label="v2.2.1">
  **Improvements:**

  * Updates [Google Drive File Picker](/resources/integrations/google-drive#using-the-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 [`getCustomWebhookUserManualUrl`](/apis/api-reference#getcustomwebhookusermanualurl) for constructing the URL of user-level [Custom Webhooks](/resources/custom-webhooks). This function can be used to prompt your user to register a Custom Webhook URL in their integration account settings.

  **Fixes:**

  * Fixes the base URL used for the Proxy API when using the SDK for on-prem environments.
</Update>

<Update label="v2.2.0">
  **Improvements:**

  * Improves the security of OAuth connection flows.

  <Warning>
    **For on-prem customers:** This SDK update requires that your instance version has been upgraded to `2025.1028` or later.

    You can verify your current version by visiting the `/infoz` path of your dashboard / login URL. Reach out to your Customer Success Manager to request an instance upgrade.
  </Warning>
</Update>

<Update label="v2.1.4">
  **Fixes:**

  * Fixes a compatibility issue between the SDK using certain Redux libraries by preventing returning internally-managed state in SDK responses.
</Update>

<Update label="v2.1.3">
  **Fixes:**

  * 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.
</Update>

<Update label="v2.1.2">
  **Improvements:**

  * Adds `installFlow.cancel()` to the [Headless Connect Portal](/connect-portal/headless-connect-portal) API to cancel in-progress installs. [Learn more](/apis/api-reference#installflowcancel)

  **Fixes:**

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

<Update label="v2.1.1">
  **Improvements:**

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

  **Fixes:**

  * Fixes types for `installIntegration` to include `selectedCredentialId` in available options.
  * Fixes connection issues for the Headless Connect Portal for certain integrations that have a PreOptionsStage, like Zendesk.
</Update>

<Update label="v2.1.0">
  **Improvements:**

  * Adds support for `oauthTimeout` option to the [`installFlow.start`](/apis/api-reference#installflowstart) 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 [`installFlow.start`](/apis/api-reference#installflowstart) to detect when the OAuth prompt is blocked by the browser or takes longer than expected.
</Update>

<Update label="v2.0.10">
  **Improvements:**

  * Adds a centralized `onError` callback for the [`installFlow.start`](/apis/api-reference#installflowstart) method of the Headless Connect Portal.

  **Fixes:**

  * 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](/connect-portal/headless-connect-portal).
</Update>

<Update label="v2.0.9">
  **Fixes:**

  * Fixes an issue where Multi-Config could not be used correctly when [sending App Events](/apis/api-reference#event) with the SDK.
</Update>

<Update label="v2.0.8">
  **Improvements:**

  * Adds support for Multi-Account Authorization for [File Pickers](/apis/api-reference#externalfilepicker).
</Update>

<Update label="v2.0.7">
  ## New: Field Mapping for all integrations

  You can now define custom Field Mapping inputs for any integration using the SDK.

  Learn more about how to use the new SDK options in the [Field Mapping documentation](/connect-portal/field-mapping#passing-your-own-integration-objects-and-fields).
</Update>

<Update label="v2.0.6">
  **Improvements:**

  * Updates `paragon.request` method to use the new URL changes introduced in the [2025-07 API release](/changelog/api#2025-07).

  **Fixes:**

  * Fixes an issue where the Headless Connect Portal might not progress to the post-OAuth stage when the OAuth prompt is completed.
</Update>

<Update label="v2.0.5">
  **Improvements:**

  * Adds support for [Box](/resources/integrations/box) File Picker.

  **Fixes:**

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

<Update label="v2.0.4">
  **Improvements:**

  * Exposes new `CredentialStatus` and `IntegrationMetadata` types from the SDK.
</Update>

<Update label="v2.0.3">
  **Improvements:**

  * Removes call to `/sdk/projects` to improve performance of SDK authentication.
</Update>

<Update label="v2.0.2">
  **Improvements:**

  * Updates return types of Headless Connect Portal function `getDataSourceOptions` to show all available fields for input sources.
</Update>

<Update label="v2.0.1">
  **Improvements:**

  * Updates `getFieldOptions` function to make `parameters` field optional.
</Update>

<Update label="v2.0.0">
  ## New: Headless Connect Portal improvements

  We have made major improvements to the Headless Connect Portal which now support all functions of the hosted Connect Portal, including User Settings, Field Mappings, and Workflows.

  See our updated documentation and example implementation [here](/connect-portal/headless-connect-portal).

  ### 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 `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

  If you are currently using the Headless Connect Portal in v1.x of the SDK, you can update your implementation to take advantage of the new functions introduced in this release.

  1. Call `.setHeadless` in your implementation to opt in to the new version of the Headless Connect Portal:
     ```js theme={null}
     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):
     ```js Migrating to installFlow theme={null}
     paragon.installIntegration("salesforce"); // [!code --]
     paragon.installFlow.start("salesforce", { // [!code ++]
         // Handle all stages of the install flow // [!code ++]
     }); // [!code ++]
     ```
</Update>