SDK / API Reference - Paragon Documentation

Below are all the public functions exposed on the Paragon SDK, which can be accessed as the named paragon export from @useparagon/connect, and the public endpoints of the Paragon REST API. Install Paragon’s JavaScript SDK with:

npm install @useparagon/connect

yarn add @useparagon/connect

pnpm add @useparagon/connect

bun add @useparagon/connect

The SDK can be imported in your client-side JavaScript files as a module:

JavaScript

import { paragon } from '@useparagon/connect';

For on-premise users

If you are using an on-premise instance of Paragon, you can call the paragon.configureGlobal function to point the SDK to use the base hostname of your Paragon instance.

JavaScript

import { paragon } from "@useparagon/connect";

// If your login URL is https://dashboard.mycompany.paragon.so:
paragon.configureGlobal({
  host: "mycompany.paragon.so",
});

SDK Methods

.authenticate

paragon.authenticate should be called at the beginning of your application’s lifecycle in all cases. This is to make sure that the userToken is always as fresh as possible, with respect to your user’s existing session on your own site.

JavaScript

await paragon.authenticate(PROJECT_ID, USER_TOKEN);

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

USER_TOKEN

string

required

See Setup for how to encode your user token

Once paragon.authenticate has been called, you can access the user’s integration state with paragon.getUser. paragon.authenticate only needs to be called when using the Paragon SDK - when making requests to the Paragon REST API, you should instead provide the Paragon User Token in the Authorization header.

.connect

Call paragon.connect to launch your Connect Portal for a specific integration provider. You can find the integrationType identifier you need in the Overview page for the integration.

JavaScript

paragon.connect(integrationType, installOptions);

Arguments:

integrationType

string

required

Type of integration (i.e. “salesforce”, “hubspot”, “googledrive”)

installOptions

InstallOptions

Show Optional installOptions

onSuccess

function

Callback invoked when an integration is successfully enabled.

onError

function

Callback if an unexpected error occurs.

accountType

enum

For integrations that support multiple account types, you can optionally designate a specific accountType to skip the account selection dialog.Example values: default, sandbox

Example of using accountType

paragon.connect("salesforce", {
  // Only allow production-type Salesforce accounts to connect
  accountType: "default",
});

mapObjectFields

object

For Field Mapping inputs that use Dynamic Application Fields. Keys must match the Application Object Name from the dashboard; values describe application fields and/or loaders for integration object types and fields. See Passing dynamic fields through the SDK.

externalId

string

Pass this option to associate a new credential with an identifier from your own system. The externalId will be available on the credential object returned by paragon.getUser.This option cannot be used with selectedCredentialId, which is used to replace or manage existing connected accounts. Existing credentials currently cannot be updated with an external ID.

selectedCredentialId

string

Used for Multi-Account Authorization. Pass this option to open the Connect Portal for an existing credential ID and update/manage settings (headful) or to start an install flow to replace an existing credential ID with a new account (with the Headless Connect Portal).

selectedConfigurationId

string

Used for Multi-Configuration. Pass this option to open the Connect Portal for a specific configuration (unique set of User Settings and Workflow Enablements for a connected credential).

This function must be called after the Paragon SDK has completed authentication. You can await the Promise returned by paragon.authenticate to show a loading state before users are able to access the Connect Portal. You must have an integration configured of this integrationType in your Paragon project for the Connect Portal to appear. Otherwise, this function does nothing. If your integration uses a Field Mapping User Setting, pass the mapping configuration through installOptions. For examples, see Passing dynamic fields through the SDK. You can also connect multiple accounts for the same integration.

Multi Account Authorization

Call paragon.subscribe to subscribe to different events and changes from the Paragon SDK. You can find the possible eventNames below:

Event Type	Usage in `paragon.subscribe`	Usage in `paragon.connect`
Integration enabled	`"onIntegrationInstall"`	`"onInstall"`
Integration disabled	`"onIntegrationUninstall"`	`"onUninstall"`
Workflow state change	`"onWorkflowChange"`	`"onWorkflowChange"`
Connect Portal opened	`"onPortalOpen"`	`"onOpen"`
Connect Portal closed	`"onPortalClose"`	`"onClose"`

Subscribing to SDK Events applies to all integrations globally. Specifying callbacks to paragon.connect only applies to a currently open Connect Portal locally.

JavaScript

paragon.subscribe(eventType, callback);

eventType

string

Event type (i.e. “onIntegrationInstall”, “onPortalOpen”) as seen in the table above

callback

(event: Event, user: AuthenticatedConnectUser) => void

callback function that triggers on event

Examples:

type IntegrationInstallEvent = {
  integrationId: string;
  integrationType: VisibleConnectAction;
  credential: Credential;
  credentialId: string;
};

// Using global subscribe
paragon.subscribe(
  "onIntegrationInstall",
  (event: IntegrationInstallEvent, user: AuthenticatedConnectUser) => {
    /* ... */
  }
);

type WorkflowStateChangeEvent = {
  integrationId: string;
  workflowId: string;
};

// Using global subscribe
paragon.subscribe(
  "onWorkflowChange",
  (event: WorkflowStateChangeEvent, user: AuthenticatedConnectUser) => {
    /* ... */
  }
);

type PortalOpenEvent = {
  integrationId: string;
  integrationType: VisibleConnectAction;
};

type PortalCloseEvent = {
  integrationId: string;
  integrationType: VisibleConnectAction;
};

// Using global subscribe
paragon.subscribe(
  "onPortalOpen",
  (event: PortalOpenEvent, user: AuthenticatedConnectUser) => {
    /* ... */
  }
);
paragon.subscribe(
  "onPortalClose",
  (event: PortalCloseEvent, user: AuthenticatedConnectUser) => {
    /* ... */
  }
);

Alternatively, you can subscribe onOpen, onClose, onUninstall , and onWorkflowChange as a one-time event locally.

type IntegrationInstallEvent = {
  integrationId: string;
  integrationType: VisibleConnectAction;
  credential: Credential;
  credentialId: string;
};

// Using local call to paragon.connect
paragon.connect("<integration>", {
  onInstall: (
    event: IntegrationInstallEvent,
    user: AuthenticatedConnectUser
  ) => {
    /* ... */
  },
});

type WorkflowStateChangeEvent = {
  integrationId: string;
  workflowId: string;
};

// Using local call to paragon.connect
paragon.connect("<integration>", {
  onWorkflowChange: (
    event: WorkflowStateChangeEvent,
    user: AuthenticatedConnectUser
  ) => {
    /* ... */
  },
});

type PortalOpenEvent = {
  integrationId: string;
  integrationType: VisibleConnectAction;
};

type PortalCloseEvent = {
  integrationId: string;
  integrationType: VisibleConnectAction;
};

// Using local call to paragon.connect
paragon.connect("<integration>", {
  onOpen: (event: PortalOpenEvent, user: AuthenticatedConnectUser) => {
    /* ... */
  },
  onClose: (event: PortalCloseEvent, user: AuthenticatedConnectUser) => {
    /* ... */
  },
});

.installIntegration

This function should be used only if you are using your own components to show connected integrations and their status, instead of the Connect Portal.Otherwise, you can use the paragon.connect function.

The paragon.installIntegration can be used to start the connection process for an integration without the Connect Portal appearing over your user interface. You can find the integrationType identifier you need in the Overview page for the integration. This function resolves with the IntegrationInstallEvent in the same format available in paragon.subscribe. You can use this to get the newly created credential by awaiting the returned Promise. This function rejects the returned Promise if the integration is already installed for the authenticated user.

JavaScript

const { credential } = await paragon.installIntegration(integrationType, installOptions);

integrationType

string

required

Type of integration (i.e. “salesforce”, “hubspot”, “googledrive”)

installOptions

InstallOptions

Show Optional installOptions

onSuccess

function

Callback invoked when an integration is successfully enabled.

onError

function

Callback if an unexpected error occurs.

accountType

enum

For integrations that support multiple account types, you can optionally designate a specific accountType to skip the account selection dialog.Example values: default, sandbox

Example of using accountType

paragon.connect("salesforce", {
  // Only allow production-type Salesforce accounts to connect
  accountType: "default",
});

mapObjectFields

object

externalId

string

selectedCredentialId

string

selectedConfigurationId

string

Used for Multi-Configuration. Pass this option to open the Connect Portal for a specific configuration (unique set of User Settings and Workflow Enablements for a connected credential).

Note: If the integration specified by integrationType requires API keys or post-authentication options, the Connect Portal will still appear to capture those values from your user at that time. The Connect Portal will automatically be dismissed after those values are entered. This function accepts the same optional install options as paragon.connect.

.uninstallIntegration

Call paragon.uninstallIntegration to disconnect an integration for the authenticated user. When an integration is disconnected, workflows for that integration will stop running for the authenticated user and any saved User Settings will be cleared.

SDK
REST API

JavaScript SDK

await paragon.uninstallIntegration(integrationType);

Arguments:

integrationType

string

required

The short name for the integration (i.e. “salesforce”, “hubspot”). Use the same name as used in paragon.connect.

HTTP

GET https://api.useparagon.com/projects/PROJECT_ID/sdk/integrations

Authorization: Bearer <Paragon User Token>

// Example Response
// [ { "id": INTEGRATION_ID, "type": "salesforce"} ]

DELETE https://api.useparagon.com/projects/PROJECT_ID/sdk/integrations/INTEGRATION_ID

Authorization: Bearer PARAGON_USER_TOKEN

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

INTEGRATION_ID

string

required

The ID of the integration to disconnect. Retrieve it from the /sdk/integrations endpoint.

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

.getIntegrationMetadata

Call paragon.getIntegrationMetadata to get the name, brandColor, and icon, for any of your active integration providers. This is a great way to create your integrations page!

SDK
REST API

JavaScript

paragon.getIntegrationMetadata();

HTTP

GET https://api.useparagon.com/projects/PROJECT_ID/sdk/metadata

Authorization: Bearer PARAGON_USER_TOKEN

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

Returns:

data

object[]

required

Show child properties

type

string

required

The integration type identifier (e.g., "salesforce", "hubspot").

name

string

required

The human-readable display name of the integration.

brandColor

string

required

The brand color hex value for the integration.

icon

string

required

The URL to the integration’s icon image.

Example Response:

JavaScript

[
  {
    "type": "salesforce",
    "name": "Salesforce",
    "brandColor": "#057ACF",
    "icon": "https://cdn.useparagon.com/2.35.0/dashboard/public/integrations/salesforce.svg"
  },
  {
    "type": "hubspot",
    "name": "Hubspot",
    "brandColor": "#F67600",
    "icon": "https://cdn.useparagon.com/2.35.0/dashboard/public/integrations/hubspot.svg"
  },
  {
    "type": "slack",
    "name": "Slack",
    "brandColor": "#4A154B",
    "icon": "https://cdn.useparagon.com/2.35.0/dashboard/public/integrations/slack.svg"
  }
]

.getIntegrationConfig

Call paragon.getIntegrationConfig to get the user-facing descriptions, User Settings, and Workflows associated with any integration.

SDK
REST API

JavaScript

paragon.getIntegrationConfig(integrationType);

Arguments:

integrationType

string

required

An integration type string, like salesforce or slack.

Example Response:

JavaScript

{
  "shortDescription": "Send notifications to Slack",
  "longDescription": "Connect your Slack workspace to receive notifications and alerts in Slack. Stay connected to important activity by bringing it all together in your Slack workspace.\n\nOur Slack integration enables you to:\n\n• Receive alerts and notifications in your Slack workspace\n• Notify or DM specific team members based on certain activity",
  "availableUserSettings": [
    {
      "id": "2d5662c9-6750-46c2-8588-2ac904532efb",
      "type": "DYNAMIC_ENUM",
      "title": "Channel",
      "required": false,
      "sourceType": "channels"
    }
  ],
  "availableWorkflows": [
    {
      "id": "2248335c-671c-47e4-b9a0-3641a9f2d301",
      "inputs": [],
      "infoText": "Send a Slack notification when a Task is created",
      "defaultEnabled": false,
      "description": "Send Slack Notification"
    }
  ],
  "hiddenWorkflows": []
}

HTTP

GET https://api.useparagon.com/projects/PROJECT_ID/sdk/integrations/INTEGRATION_TYPE

Authorization: Bearer PARAGON_USER_TOKEN

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

INTEGRATION_TYPE

string

required

An integration type string, like salesforce or slack.

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

Example Response:

JavaScript

[{
  "id": "2f08e65f-d924-42ab-9618-b6023d82ffbd",
  "projectId": "908f4c5e-6394-46a5-9355-3f729edbd160",
  "customIntegrationId": null,
  "type": "slack",
  "isActive": true,
  "configs": [
    {
      "id": "3ebcc179-a1a6-447f-8dc9-5017f40f08ef",
      "values": {
        "overview": "####Our Slack integration enables you to:\n   \n\n• Receive alerts and notifications in your Slack workspace\n• Notify or DM specific team members based on certain activity",
        "sharedMeta": {},
        "accentColor": "#4A154B",
        "description": "Send notifications to Slack",
        "workflowMeta": {}
      }
    },
  ],
  "workflows": [
    {
      "id": "1b22193b-e355-458d-b6a3-5e5516edb588",
      "description": "Send Updates to Slack",
      "projectId": "908f4c5e-6394-46a5-9355-3f729edbd160",
      "integrationId": "2f08e65f-d924-42ab-9618-b6023d82ffbd",
      "steps": []
    }
  ],
  "customIntegration": null,
  "hasCredential": true,
  "connectedUserLimitOnDevCred": 0,
  "connectedUserLimitReached": true,
  "name": "Slack",
  "brandColor": "#4A154B",
  "needPreOauthInputs": false,
  "providerType": "slack",
  "authenticationType": "oauth"
}]

.getUser

Call paragon.getUser to retrieve the currently authenticated user and their connected integration state.

SDK
REST API

JavaScript

paragon.getUser();

HTTP

GET https://api.useparagon.com/projects/PROJECT_ID/sdk/me

Authorization: Bearer PARAGON_USER_TOKEN

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

Example Response:

JavaScript

{
  authenticated: true,
  userId: "xyz",
  integrations: {
    salesforce: {
      configuredWorkflows: {},
      credentialId: "987654-56a7-89b1-cd23-456789abcdef",
      credentialStatus: "VALID",
      enabled: true,
      providerData: {
        instanceURL: "https://mycompany.my.salesforce.com"
      },
      providerId: "1234567890"
    },
    shopify: {
      configuredWorkflows: {},
      enabled: false
    }
  }
}

If the user is not authenticated, you’ll receive back only { authenticated: false } instead. Please check the authenticated property before using the user.integrations field.

.setUserMetadata

Call paragon.setUserMetadata to associate the authenticated user with metadata from your application. This metadata can be accessed with paragon.getUser or retrieved over the API.

SDK
REST API

JavaScript SDK

paragon.setUserMetadata(metadata);

Arguments:

metadata

object

required

Metadata object to associate with the authenticated user.

HTTP

PATCH https://api.useparagon.com/projects/PROJECT_ID/sdk/me

// Headers
Authorization: PARAGON_USER_TOKEN
Content-Type: application/json

// Body
{ ...metadata }

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

metadata

object

required

Metadata object to associate with the authenticated user.

Examples:

paragon.setUserMetadata({
  Name: "Sean V",
  Email: "[email protected]",
  apiKey: "key_Y0kBVldPFInxK",
});

Request

PATCH https://api.useparagon.com/projects/<Project ID>/sdk/me

// Headers
Authorization: <Paragon User Token>
Content-Type: application/json

// Body
{ "meta": { "Email": "[email protected]", "apiKey": "key_Y0kBVldPFInxK" } }

.updateIntegrationUserSettings

Call paragon.updateIntegrationUserSettings to update any integration-level User Settings for your Connected User.

JavaScript

paragon.updateIntegrationUserSettings(integrationType, userSettingsUpdate, options);

Arguments:

integrationType

string

required

An integration type string, like salesforce.

userSettingsUpdate

object

required

A partial update object where the keys are the id properties of User Settings objects (which you can get from paragon.getIntegrationConfig) and the values are the user’s selection for the matching input type.Any keys that are not included in the object will not be updated.The type for each value will depend on the input type. See Input Types Reference to see the value type for each input.

Example

{
  "1f7474a5-8b8e-4c25-8d44-29f20aec3fe4": "general"
}

options

CredentialConfigOptions | undefined

Optionally specify a Credential and Configuration to target, if using Multi-Account Authorization or Multi-Configuration.

Show child properties

selectedCredentialId

string

The Credential ID (a UUID) of the connected account you want to update, if using Multi-Account Authorization.

selectedConfigurationId

string

The Configuration ID (a UUID or an External ID prefixed with ext:), if using Multi-Configuration.

.getDataSourceOptions

Call paragon.getDataSourceOptions to get configuration details for compound data sources used for dynamic User Settings types in the Headless Connect Portal. Compound data sources, for Field Mapping and Combo Dropdown inputs, have multiple data sources within them (Field Mappings have both Object Types and Field Names as sources). To load options for a data source, see paragon.getFieldOptions.

SDK 2.3.0+: Consider using paragon.getSourcesForInput instead, which provides a simpler way to get all data sources needed for any input type in a single call.

JavaScript

await paragon.getDataSourceOptions(integrationType, sourceType);

Arguments:

integrationType

string

required

An integration type string, like salesforce.

sourceType

string

required

A source type string, which can be found in the sourceType property of a User Setting object from paragon.getIntegrationConfig or from stage.options of PostOptionsStage.

Examples:

await paragon.getDataSourceOptions(
  "salesforce",
  "customObjectMapping",
);

// Returns:
{
  "id": "customObjectMapping",
  "type": "FIELD_MAPPER_DATA_SOURCE",
  "title": "Field Mapping",
  "subtitle": "Allows users to define a field mapping",
  "recordSource": {
    "type": "DYNAMIC_DATA_SOURCE",
    "title": "Record Type",
    "cacheKey": "recordTypes",
  },
  "fieldSource": {
    "type": "DYNAMIC_DATA_SOURCE",
    "title": "Field",
    "cacheKey": "cachedFields",
  },
}

await paragon.getDataSourceOptions(
  "jira",
  "projectIssueStatusTypeCombo",
);

// Returns:
{
  "id": "projectIssueStatusTypeCombo",
  "type": "COMBO_INPUT_DATA_SOURCE",
  "title": "Issue Status",
  "subtitle": "The stage the issue is at, e.g. To Do or Done",
  "mainInputSource": {
    "type": "DYNAMIC_DATA_SOURCE",
    "cacheKey": "projects",
    "title": "Project",
    "subtitle": "Jira project that issues can be created in",
  },
  "dependentInputSource": {
    "type": "DYNAMIC_DATA_SOURCE",
    "cacheKey": "issueIssueStatusByProject",
    "title": "Issue Status",
    "subtitle": "The stage the issue is at, e.g. To Do or Done",
  }
}

.getFieldOptions

Load options from an integration data source for dynamic User Settings types in the Headless Connect Portal, using the Connected User’s account. paragon.getFieldOptions can only be called for data sources with type DYNAMIC_DATA_SOURCE (for dynamic enum input types).

Compound data sources like FIELD_MAPPER_DATA_SOURCE or COMBO_INPUT_DATA_SOURCE are composed of DYNAMIC_DATA_SOURCE-type sources.
When rendering Field Mapping or Combo Dropdown inputs, first identify each data source with paragon.getSourcesForInput (or paragon.getDataSourceOptions), and use the returned data source configuration to call paragon.getFieldOptions. See a full example.

This function supports search and pagination; see the parameters for fieldOptions below to learn more.

SDK
REST API

JavaScript SDK (Field Mapping)

  await paragon.getFieldOptions(fieldOptions);

Arguments:

fieldOptions

FieldOptions

required

Show child properties

integration

string

required

An integration type string, like salesforce.

action

string

A source type string, which can be found in the sourceType property of a User Setting object from paragon.getIntegrationConfig or from stage.options of PostOptionsStage.Either action or source must be provided.

source

DynamicDataSource

A DynamicDataSource object, as returned by paragon.getSourcesForInput. When provided, the cacheKey of the source is used to identify the data source to load options from.Either action or source must be provided.

string

A user-provided search query for an option. When provided, the data source will return options that match this query.

cursor

string

A page cursor to use to load subsequent pages of results. The response of paragon.getFieldOptions will provide nextPageCursor to use or null if there are no more results.

parameters

Parameter[]

When loading options for a compound data source (e.g. fieldSource of a Field Mapping input or dependentInputSource of a Combo Dropdown input), pass parameters with the user’s selection from the first input (e.g. the Record Type for Field Mapping).

Show child properties

key

string

The cacheKey property of the primary/first input in the compound data sources (e.g. recordSource of a Field Mapping input or mainInputSource of a Combo Dropdown input).

source

string

Show child properties

type

const

required

Set this to "VALUE".

value

string

required

Set this to the value property of the user’s selection.

selectedCredentialId

string

If you are using Multi-Account Authorization and there may be more than one account connected for a given integration, pass selectedCredentialId to load options for the current account.

HTTP

POST https://api.useparagon.com/projects/PROJECT_ID/sdk/actions

Authorization: Bearer PARAGON_USER_TOKEN
Content-Type: application/json

{
  ...fieldOptions
}

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

fieldOptions

FieldOptions

required

Show child properties

integration

string

required

An integration type string, like salesforce.

action

string

source

DynamicDataSource

string

A user-provided search query for an option. When provided, the data source will return options that match this query.

cursor

string

A page cursor to use to load subsequent pages of results. The response of paragon.getFieldOptions will provide nextPageCursor to use or null if there are no more results.

parameters

Parameter[]

Show child properties

key

string

The cacheKey property of the primary/first input in the compound data sources (e.g. recordSource of a Field Mapping input or mainInputSource of a Combo Dropdown input).

source

string

Show child properties

type

const

required

Set this to "VALUE".

value

string

required

Set this to the value property of the user’s selection.

selectedCredentialId

string

If you are using Multi-Account Authorization and there may be more than one account connected for a given integration, pass selectedCredentialId to load options for the current account.

Returns:

data

Option[] | Section[]

required

Show child properties

data will be an Array of either Option or Section objects, which should be handled by your Dropdown input.

Option
Section

label

string

required

The human-readable display name to use for this option when displaying it to your user.

value

string

required

The unique value of this option to save with paragon.setPreOptions, paragon.setPostOptions, paragon.updateIntegrationUserSettings, or paragon.updateWorkflowUserSettings. This value can also be passed as parameters[].source.value for dependent inputs of compound data sources.

nestedData

object[]

This section is an empty array for all input types except for Default value mapping, which is only supported by Jira: Issue Field Values.

nextPageCursor

string | null

The cursor value to pass as cursor for the next page of results.

Examples:

await paragon.getFieldOptions({
  integration: "slack",
  action: "channels",
  search: "general",
});

// Returns:
{
  "data": [
    {
      "label": "#general",
      "value": "general"
    },
  ],
  "nestedData": [],
  "nextPageCursor": "dGVhbTpDMDUxWjlNSzk4Vw=="
}

// Load Record Types:
await paragon.getFieldOptions({
  integration: "salesforce",
  action: "recordTypes", // from `recordSource.cacheKey` of data source options
});

// Load Fields: 
await paragon.getFieldOptions({
  integration: "salesforce",
  action: "cachedFields", // from `fieldSource.cacheKey` of data source options
  parameters: [{
    "key": "recordTypes",
    "source": {
      "type": "VALUE",
      "value": "Task" // The `value` property of the user's input
    }
  }],
});

REST API

POST https://api.useparagon.com/projects/<Paragon Project ID>/sdk/actions

Authorization: Bearer <Paragon User Token>
Content-Type: application/json

{
  "action": "salesforce",
  "sourceKey": "cachedFields",
  "parameters": [{
    "key": "recordTypes",
    "source": {
      "type": "VALUE",
      "value": "Task"
    }
  }],
  "paginationParameters": {
    "pageCursor": 0,
    "search": ""
  }
}

.getSourcesForInput

Call paragon.getSourcesForInput to get all the data sources needed to render a dynamic input (e.g. a picklist loaded from integration data from the user’s connected account). The returned data sources can be passed directly to paragon.getFieldOptions using the source parameter to load options for your input, with pagination and search.

JavaScript

const config = paragon.getIntegrationConfig(integrationType, input);

Arguments:

integrationType

string

required

An integration type string, like salesforce.

input

Input

required

The input object from availableUserSettings, availableWorkflows[n].inputs, or stage.options of an install flow stage.

Returns: Returns null for inputs that don’t require a data source (e.g. text inputs). Otherwise, returns one of the following based on the Input Type of the input:

SingleSource
FieldMapperSources
ComboSources
DefaultFieldValueSources

Returned for DynamicEnum and CustomDropdown input types.

kind

const

required

"single" for SingleSource.

source

DynamicDataSource | StaticEnumDataSource

required

The data source for the input. Pass this to paragon.getFieldOptions using the source parameter to load options.

Example:

DynamicEnum input

const config = paragon.getIntegrationConfig("slack");
const input = config.availableUserSettings[0];
// { id: "...", type: "DYNAMIC_ENUM", title: "Channel", sourceType: "channels" }

const sources = paragon.getSourcesForInput("slack", input);
// { kind: "single", source: { type: "DYNAMIC_DATA_SOURCE", cacheKey: "channels", ... } }

if (sources?.kind === "single") {
  const options = await paragon.getFieldOptions({
    integration: "slack",
    source: sources.source,
  });
  // { data: [{ label: "#general", value: "general" }, ...], nextPageCursor: "..." }
}

Returned for FieldMapper input types.

kind

const

required

"fieldMapper" for FieldMapperSources.

recordSource

DynamicDataSource

required

The data source for loading record types. Pass to paragon.getFieldOptions to load record type options.

fieldSource

DynamicDataSource

required

The data source for loading fields. Pass to paragon.getFieldOptions with parameters for the selected record type to load available fields.

dependentInputSource

DynamicDataSource

An optional data source for a dependent input within the field mapping.

mapObjectFieldOptions

DynamicMappingOptions | DynamicMappingField[]

Pre-configured field mapping options, if provided via paragon.setDataSources.

Example:

FieldMapper input

const config = paragon.getIntegrationConfig("salesforce");
const input = config.availableUserSettings[0];
// { id: "...", type: "FIELD_MAPPER", title: "Map fields", sourceType: "customObjectMapping" }

const sources = paragon.getSourcesForInput("salesforce", input);
// { kind: "fieldMapper", recordSource: {...}, fieldSource: {...} }

if (sources?.kind === "fieldMapper") {
  // Load record types
  const recordTypes = await paragon.getFieldOptions({
    integration: "salesforce",
    source: sources.recordSource,
  });

  // Load fields for a selected record type
  const fields = await paragon.getFieldOptions({
    integration: "salesforce",
    source: sources.fieldSource,
    parameters: [{
      key: sources.recordSource.cacheKey,
      source: { type: "VALUE", value: "Task" },
    }],
  });
}

Returned for ComboInput input types (e.g. Combo Dropdown).

kind

const

required

"combo" for ComboSources.

mainInputSource

DynamicDataSource

required

The data source for the primary input. Pass to paragon.getFieldOptions to load main options.

dependentInputSource

DynamicDataSource

required

The data source for the dependent input. Pass to paragon.getFieldOptions with parameters for the user’s main selection.

Example:

ComboInput

const config = paragon.getIntegrationConfig("jira");
const input = config.availableUserSettings[0];
// { id: "...", type: "COMBO_INPUT", sourceType: "projectIssueStatusTypeCombo" }

const sources = paragon.getSourcesForInput("jira", input);
// { kind: "combo", mainInputSource: {...}, dependentInputSource: {...} }

if (sources?.kind === "combo") {
  // Load main options (e.g. Projects)
  const projects = await paragon.getFieldOptions({
    integration: "jira",
    source: sources.mainInputSource,
  });

  // Load dependent options (e.g. Issue Statuses for a selected Project)
  const statuses = await paragon.getFieldOptions({
    integration: "jira",
    source: sources.dependentInputSource,
    parameters: [{
      key: sources.mainInputSource.cacheKey,
      source: { type: "VALUE", value: "PROJECT-1" },
    }],
  });
}

Returned for DynamicComboInput input types.

kind

const

required

"defaultFieldValue" for DefaultFieldValueSources.

mainInputSource

DynamicDataSource

required

The data source for the primary input. Pass to paragon.getFieldOptions to load main options.

dependentInputSource

DynamicDataSource

required

The data source for the dependent input. Pass to paragon.getFieldOptions with parameters for the user’s main selection.

variableInputSource

DynamicDataSource

An optional data source for a variable input.

Example:

DynamicComboInput

const config = paragon.getIntegrationConfig("salesforce");
const input = config.availableUserSettings[0];
// { id: "...", type: "DYNAMIC_COMBO_INPUT", sourceType: "dynamicComboAction" }

const sources = paragon.getSourcesForInput("salesforce", input);
// { kind: "defaultFieldValue", mainInputSource: {...}, dependentInputSource: {...}, variableInputSource: {...} }

if (sources?.kind === "defaultFieldValue") {
  const mainOptions = await paragon.getFieldOptions({
    integration: "salesforce",
    source: sources.mainInputSource,
  });

  const dependentOptions = await paragon.getFieldOptions({
    integration: "salesforce",
    source: sources.dependentInputSource,
    parameters: [{
      key: sources.mainInputSource.cacheKey,
      source: { type: "VALUE", value: mainOptions.data[0].value },
    }],
  });
}

.setDataSources

Call paragon.setDataSources to register custom data sources for dropdown and field mapping inputs when using the Headless Connect Portal. This can be used in place of passing dropdowns and mapObjectFields inline with paragon.connect, for Headless Connect Portal implementations. Data sources can be registered globally (applied to all integrations) or for specific integrations. When an integration-specific source exists, it takes priority over a global source with the same key. This function should be called once after paragon.setHeadless and before rendering any inputs.

JavaScript

paragon.setDataSources(config);

Arguments:

config

SetDataSourcesConfig

required

Hide child properties

dropdowns

Record<string, CustomDropdownField[] | CustomDropdownOptions>

Global custom dropdown data sources, keyed by the dropdown key identifier. Values can be either a static array of CustomDropdownField[] options (objects with label and value strings), or a CustomDropdownOptions object for dynamic loading:

Static dropdown options

paragon.setDataSources({
  dropdowns: {
    my_custom_dropdown: [
      { label: "Option A", value: "a" },
      { label: "Option B", value: "b" },
    ],
  },
});

Show child properties (CustomDropdownOptions)

loadOptions

(cursor?: string, search?: string) => Promise<{ options: CustomDropdownField[], nextPageCursor: string | null }>

required

A function that returns dropdown options with support for pagination and search. Called by the SDK when options need to be loaded or refreshed.

refreshOnOpen

boolean

If true, the dropdown options will be reloaded every time the dropdown is opened. Useful for dependent dropdowns where options depend on other input values. Defaults to false.

Dynamic dropdown with loader

paragon.setDataSources({
  dropdowns: {
    my_dynamic_dropdown: {
      loadOptions: async (cursor, search) => {
        const response = await fetch(`/api/options?cursor=${cursor}&search=${search}`);
        const data = await response.json();
        return {
          options: data.items,
          nextPageCursor: data.nextCursor,
        };
      },
    },
  },
});

mapObjectFields

Record<string, DynamicMappingField[] | DynamicMappingOptions | DynamicFieldMappingConfig>

Global field mapping data sources, keyed by field mapping name. Values can be one of the following:

Show child properties (DynamicMappingField)

Option 1: DynamicMappingField[] - Static array of mapping options.

label

string

required

The display label for the field.

value

string

required

The value identifier for the field.

Show child properties (DynamicMappingOptions)

Option 2: DynamicMappingOptions — Configurable mapping behavior with static fields.

fields

DynamicMappingField[]

required

The list of available fields (objects with label and value strings).

defaultFields

string[]

Field values that should be selected by default.

userCanRemoveMappings

boolean

Whether users can remove field mappings.

userCanCreateFields

boolean

Whether users can create new fields.

Show child properties (DynamicFieldMappingConfig)

Option 3: DynamicFieldMappingConfig — Fully dynamic field mapping with loader functions for fetching object types and fields at runtime.

objectTypes.get

(cursor?: string, search?: string) => Promise<{ options: { label: string, value: string }[], nextPageCursor: string | null }>

required

A loader function to fetch available object types with pagination and search support.

integrationFields.get

(params: { objectType: string }, cursor?: string, search?: string) => Promise<{ options: { label: string, value: string }[], nextPageCursor: string | null }>

required

A loader function to fetch available fields for a given object type with pagination and search support.

applicationFields

object

Optional configuration for application-side fields.

Show child properties

fields

{ label: string, value: string }[]

required

The list of application fields available for mapping.

defaultFields

string[]

Field values that should be selected by default.

userCanRemoveMappings

boolean

Whether users can remove field mappings.

userCanCreateFields

boolean

Whether users can create new fields.

Field mapping with BYO loaders

paragon.setDataSources({
  mapObjectFields: {
    myFieldMapping: {
      objectTypes: {
        get: async (cursor, search) => {
          const response = await fetch(`/api/object-types?cursor=${cursor}&search=${search}`);
          const data = await response.json();
          return { options: data.items, nextPageCursor: data.nextCursor };
        },
      },
      integrationFields: {
        get: async ({ objectType }, cursor, search) => {
          const response = await fetch(
            `/api/fields?objectType=${objectType}&cursor=${cursor}&search=${search}`
          );
          const data = await response.json();
          return { options: data.items, nextPageCursor: data.nextCursor };
        },
      },
      applicationFields: {
        fields: [
          { label: "Name", value: "name" },
          { label: "Email", value: "email" },
        ],
      },
    },
  },
});

integrationSpecificSources

Record<string, { dropdowns?, mapObjectFields? }>

Integration-specific data sources that take priority over global sources. Keyed by integration type (e.g. "salesforce"), with the same dropdowns and mapObjectFields structure.

Integration-specific sources

paragon.setDataSources({
  dropdowns: {
    departments: [
      { label: "Engineering", value: "eng" },
      { label: "Sales", value: "sales" },
    ],
  },
  integrationSpecificSources: {
    salesforce: {
      dropdowns: {
        departments: [
          { label: "Engineering", value: "engineering" },
          { label: "Sales", value: "sales-dept" },
          { label: "Marketing", value: "marketing" },
        ],
      },
    },
  },
});

.enableWorkflow

Call paragon.enableWorkflow to turn on a workflow for a user by ID.

SDK
REST API

JavaScript

paragon.enableWorkflow(workflowId);

Arguments:

workflowId

string

required

Workflow ID

HTTP

POST https://api.useparagon.com/projects/PROJECT_ID/sdk/workflows/WORKFLOW_ID

Authorization: Bearer PARAGON_USER_TOKEN

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

WORKFLOW_ID

string

required

Workflow ID

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

.disableWorkflow

Call paragon.disableWorkflow to turn off a workflow for a user by ID.

SDK
REST API

JavaScript

paragon.disableWorkflow(workflowId);

Arguments:

workflowId

string

required

Workflow ID

HTTP

DELETE https://api.useparagon.com/projects/PROJECT_ID/sdk/workflows/WORKFLOW_ID

Authorization: Bearer PARAGON_USER_TOKEN

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

WORKFLOW_ID

string

required

Workflow ID

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

.updateWorkflowState

Call paragon.updateWorkflowState to enable or disable workflows for a user.

JavaScript

paragon.updateWorkflowState(workflowStateUpdate, options);

Arguments:

workflowStateUpdate

object

required

A partial update object where keys are workflow IDs and values are true or false. Any workflow IDs not included in this object will not be updated in this call.

on Example

{
  "bb89897b-ec2a-4118-b091-c12713c6bffa": true,
  "487c67e1-bc3f-406e-acc4-085f897dc564": false,
}

options

CredentialConfigOptions | undefined

Optionally specify a Credential and Configuration to target, if using Multi-Account Authorization or Multi-Configuration.

Show child properties

selectedCredentialId

string

The Credential ID (a UUID) of the connected account you want to update, if using Multi-Account Authorization.

selectedConfigurationId

string

The Configuration ID (a UUID or an External ID prefixed with ext:), if using Multi-Configuration.

.updateWorkflowUserSettings

Call paragon.updateWorkflowUserSettings to update any workflow-level User Settings for your Connected User.

JavaScript

paragon.updateWorkflowUserSettings(integrationType, workflowId, userSettingsUpdate, options);

Arguments:

integrationType

string

required

An integration type string, like salesforce.

workflowId

string

required

The ID of the Workflow that the workflow-level User Setting you are modifying belongs to. If you are trying to modify an integration-level User Setting, call paragon.updateIntegrationUserSettings instead.

userSettingsUpdate

object

required

Example

{
  "1f7474a5-8b8e-4c25-8d44-29f20aec3fe4": "general"
}

options

CredentialConfigOptions | undefined

Optionally specify a Credential and Configuration to target, if using Multi-Account Authorization or Multi-Configuration.

Show child properties

selectedCredentialId

string

The Credential ID (a UUID) of the connected account you want to update, if using Multi-Account Authorization.

selectedConfigurationId

string

The Configuration ID (a UUID or an External ID prefixed with ext:), if using Multi-Configuration.

.getCustomWebhookUserManualUrl

If you are using Custom Webhooks with a User-Level URL and Manual Setup, you can use paragon.getCustomWebhookUserManualUrl to construct the user-specific URL that must be registered by your customer in the integration to complete webhook setup. There is no API endpoint available for this method. However, you can construct the user-specific URL without the JavaScript SDK as described in the Custom Webhooks docs.

JavaScript

// Present this value to your user to register this webhook in their account manually
const webhookUrl = paragon.getCustomWebhookUserManualUrl(workflowId, credentialId);

Arguments:

workflowId

string

required

The ID of a Workflow that utilizes this Custom Webhook. If the same Custom Webhook is used in multiple Workflows, any one of these workflows can be used as workflowId.

credentialId

string

If you are using Multi-Account Authorization and there may be more than one account connected for a given integration, pass the credentialId to ensure that received events are routed to the correct account.

.workflow

Call paragon.workflow to trigger a Paragon workflow that sends a custom response back to your app. Note: The workflow must be enabled and use a Request-type trigger.

SDK
REST API

JavaScript

await paragon.workflow(workflowId, options);

Arguments:

workflowId

string

required

The ID of the workflow to trigger.

options

FetchOptions

Show Optional FetchOptions

body

object

The request body to pass to the workflow trigger.

Example:

paragon.authenticate(PROJECT_ID, PARAGON_USER_TOKEN);

await paragon.workflow(WORKFLOW_ID, {
  "body": {
    "email": "[email protected]",
    "first_name": "Bowie",
    "last_name": "Foo"
  }
});

HTTP

POST https://api.useparagon.com/projects/PROJECT_ID/sdk/triggers/WORKFLOW_ID

Authorization: Bearer PARAGON_USER_TOKEN
Content-Type: application/json

{
  ...options
}

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

WORKFLOW_ID

string

required

The ID of the workflow to trigger.

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

options

FetchOptions

Show Optional FetchOptions

body

object

The request body to pass to the workflow trigger.

Example:

HTTP

POST https://api.useparagon.com/projects/PROJECT_ID/sdk/triggers/WORKFLOW_ID

Authorization: Bearer PARAGON_USER_TOKEN
Content-Type: application/json

{
  "email": "[email protected]",
  "first_name": "Bowie",
  "last_name": "Foo"
}

.request

Call paragon.request to send an API request to a third-party integration on behalf of one of your users. Every integration in your dashboard has a code example of using paragon.request.

JavaScript

await paragon.request(integrationType, path, requestOptions);

Arguments:

integrationType

string

required

The short name for the integration (i.e. “salesforce” or “googleCalendar”). You can find this string on the Overview tab of the integration you want to access, on your Paragon dashboard.

path

string

required

The path (without the hostname) of the API request you are trying to access. An example might be: “/v1/charges” for Stripe’s charge API or “chat.postMessage” for Slack’s Web API.

requestOptions

object

Optional request options to include:

Show child properties

body

object

An object representing JSON contents of the request.

method

string

An HTTP verb such as “GET” or “POST”. Defaults to GET.

headers

object

Additional HTTP headers to include in the request.

If requestOptions is omitted, the SDK issues a GET request without a body.

The function returns a promise for the request output, which will have a shape that varies depending on the integration and API endpoint. Examples:

await paragon.request('slack', '/chat.postMessage', {
	method: 'POST',
	body: {
		channel: 'CXXXXXXX0' // Channel ID,
		text: 'This message was sent with Paragon Connect :exploding_head:'
	}
});

// -> Responds with { ok: true }, and sends a message :)

POST https://proxy.useparagon.com/projects/<Paragon Project ID>/sdk/proxy/slack/chat.postMessage

Authorization: Bearer <Paragon User Token>
Content-Type: application/json

{
    "channel": "CXXXXXXX0",
    "text": "This message was sent with Paragon Connect :exploding_head:"
}

// -> Responds with { output: { ok: true }}, and sends a message :)

.event

App Events can be sent from your application using the Paragon SDK or REST API. In both cases, you must pass two parameters:

name - the event name defined in your App Event
payload - the event payload that should match the event schema defined in your App Event

See the code examples below for how to send App Events using the Paragon SDK or API.

SDK
REST API

JavaScript

var eventName = "Contact Created";
var eventPayload = { "name": "Brandon", "email": "[email protected]" };

paragon.event(eventName, payload);

Arguments:

eventName

string

required

The event name defined in your App Event

payload

object

required

The event payload that should match the event schema defined in your App Event

HTTP

POST https://api.useparagon.com/projects/PROJECT_ID/sdk/events/trigger

Authorization: Bearer PARAGON_USER_TOKEN
Content-Type: application/json

{
    "name": "Contact Created",
    "payload": {
        "name": "Brandon",
        "email": "[email protected]"
    }
}

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

name

string

required

The event name defined in your App Event

payload

object

required

The event payload that should match the event schema defined in your App Event

When sending live events from your application, Paragon will not validate that your event payload matches the defined event schema.

.setHeadless

Call paragon.setHeadless to enable or disable Headless mode for the SDK. When headless mode is enabled, the SDK will not render the Connect Portal UI and will instead expose functions for you to build your own UI.

JavaScript

paragon.setHeadless(true);

This should be called once after SDK initialization. See the Headless Connect Portal guide for more details.

API Only

`GET` project’s integrations

Returns a list of the integrations enabled for the Paragon project by the ID in the URL.

Includes the Connect Portal configuration for each integration (as .configs) and the Workflows associated with each integration (as .workflows)

You can use paragon.getIntegrationMetadata and paragon.getIntegrationConfig when using the JavaScript SDK.

HTTP

GET https://api.useparagon.com/projects/PROJECT_ID/sdk/integrations

Authorization: Bearer PARAGON_USER_TOKEN
Content-Type: application/json

// Example response (may include more than is in this list):

[{
  "id": "2f08e65f-d924-42ab-9618-b6023d82ffbd",
  "projectId": "908f4c5e-6394-46a5-9355-3f729edbd160",
  "customIntegrationId": null,
  "type": "slack",
  "isActive": true,
  "configs": [
    {
      "id": "3ebcc179-a1a6-447f-8dc9-5017f40f08ef",
      "values": {
        "overview": "####Our Slack integration enables you to:\n   \n\n• Receive alerts and notifications in your Slack workspace\n• Notify or DM specific team members based on certain activity",
        "sharedMeta": {},
        "accentColor": "#4A154B",
        "description": "Send notifications to Slack",
        "workflowMeta": {}
      }
    },
  ],
  "workflows": [
    {
      "id": "1b22193b-e355-458d-b6a3-5e5516edb588",
      "description": "Send Updates to Slack",
      "projectId": "908f4c5e-6394-46a5-9355-3f729edbd160",
      "integrationId": "2f08e65f-d924-42ab-9618-b6023d82ffbd",
      "steps": []
    }
  ],
  "customIntegration": null,
  "hasCredential": true,
  "connectedUserLimitOnDevCred": 0,
  "connectedUserLimitReached": true,
  "name": "Slack",
  "brandColor": "#4A154B",
  "needPreOauthInputs": false,
  "providerType": "slack",
  "authenticationType": "oauth"
}]

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

`GET` user’s Connect credentials

Returns a list of the user’s Connect credentials (i.e., the accounts connected and authorized by the end user).

The providerId is the authenticated user’s ID assigned by their integration provider (e.g. for a Salesforce integration, this would be the user’s Salesforce user ID)

This method is currently available via REST API only.

HTTP

GET https://api.useparagon.com/projects/PROJECT_ID/sdk/credentials

Authorization: Bearer PARAGON_USER_TOKEN
Content-Type: application/json

// Example response (may include more than is in this list):

[{
  "id": "00da4146-7ac4-4253-a8f7-96849b8137d9",
  "dateCreated": "2021-03-24T12:19:21.511Z",
  "dateUpdated": "2021-03-24T12:19:28.512Z",
  "dateDeleted": null,
  "projectId": "db06d291-ba2c-41c5-9a12-9362abfd6228",
  "integrationId": "95bedc9f-6a22-4855-b08d-e68dc073ad91",
  "personaId": "0563109f-5e71-46c5-8483-1ac8c0913d6c",
  "config": {
    "configuredWorkflows": {
      "3eb95154-3c7b-413c-bf14-ba367d95b53f": {
        "enabled": true,
        "settings": {
					"example-input-id": "example value"
				}
      }
    }
  },
  "isPreviewCredential": false,
  "providerId": "50150244515"
}]

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

`UPDATE` user’s Connect credential

Updates the user’s connected integration account, including any settings and configured workflows. This endpoint updates by replacement with respect to the config property, so this endpoint should only be used after retrieving the existing value (which can be done by using the above endpoint: Get user’s Connect credentials). Alternatively, you can use the SDK to update User Settings or workflow enablements:

paragon.updateIntegrationUserSettings: Update integration-level User Settings.
paragon.updateWorkflowUserSettings: Update workflow-level User Settings.
paragon.updateWorkflowState: Update workflow enablements.

HTTP

PATCH https://api.useparagon.com/projects/PROJECT_ID/sdk/credentials/CREDENTIAL_ID

Authorization: Bearer <Paragon User Token>
Content-Type: application/json

// Body: Example showing WORKFLOW_ID being enabled
{
    "config": {
        "configuredWorkflows": {
            ...
            WORKFLOW_ID: {
                "enabled": true,
                "settings": {}
            }
        },
        "sharedSettings": {...}
    }
}

Arguments:

PROJECT_ID

string

required

You can find your project ID in the Overview tab of any Integration

CREDENTIAL_ID

string

required

The ID of the Connect credential to update. Retrieve it from the /sdk/credentials endpoint.

PARAGON_USER_TOKEN

string

required

See Setup for how to encode your user token

config

object

required

The configuration object to update. This will replace the existing config property entirely, so you must provide the full existing value with your intended changes applied.

Note: In the above example, the existing value for config must be provided in full, with the intended changes applied. This is because config will be updated by replacement.

Headless Connect installFlow

Use paragon.installFlow when implementing the Headless Connect Portal to guide your user through the installation process for an integration. InstallFlowStage: These are the possible install flow stages received in the onNext callback of InstallFlow that should be rendered by your app to guide the user through the installation process.

AccountTypeStage
PreOptionsStage
PostOptionsStage
InstructionStage

In the AccountTypeStage, the user should be prompted with a list of account types that they can choose from.If you want to skip this stage, pass the first account type option (or "default") to paragon.installFlow.setAccountType to move to the next stage.

Example (Salesforce)

{
  "stage": "accountType",
  "options": [
    { "id": "default", "accountDescription": "Production Account" },
    { "id": "sandbox", "accountDescription": "Sandbox Account"}
  ]
}

stage

const

"accountType" for AccountTypeStage.

options

AccountType[]

The list of account types that the user can choose from.

Show child properties

string

required

The ID of the account type. Pass this to paragon.installFlow.setAccountType when the user selects an option.

accountDescription

string

The human-readable description of the account type.

In the PreOptionsStage, the user should be prompted with inputs to collect the necessary details for API key authorization or for the next OAuth stage in the flow.

Example (Shopify)

{
  "stage": "preOptions",
  "options": [
    {
      "id": "SHOP_NAME",
      "title": "Enter your Shopify username",
      "subtitle": "Enter your Shopify username, e.g. https://<username>.myshopify.com.",
      "placeholder": "username",
      "type": "TEXT_NO_VARS"
    }
  ]
}

stage

const

"preOptions" for PreOptionsStage.

options

InputType[]

The list of inputs to prompt the user with in this stage. You can see a full list of input types that are used by the Connect Portal and must be rendered by your implementation in Input Types Reference.

Show child properties

string

required

Use the input id as the key of the object you pass to paragon.setPreOptions. The value will be the input provided by the user.

type

enum

required

The type of this input, which will be one of the inputs in Input Types Reference.

title

string

required

The title to display to the user to describe this input.

subtitle

string

The descriptive text to display to the user to further describe or provide context to this input.

placeholder

string

The placeholder or example value to display to the user.

In the PostOptionsStage, the user should be prompted with inputs to finalize their account setup after the OAuth flow.

Example (Jira)

{
  "stage": "postOptions",
  "credentialId": "987654-56a7-89b1-cd23-456789abcdef",
  "options": [
    {
      "id": "JIRA_CLOUD_ID",
      "type": "DYNAMIC_ENUM",
      "title": "Choose a Jira site to connect.",
      "subtitle": "The Jira site, where all operations will be performed.",
      "sourceType": "getAvailableSites",
      "required": true
    }
  ],
  "done": false
}

stage

const

"postOptions" for PostOptionsStage.

credentialId

string

The ID of the credential that was created during the OAuth flow. Available once the credential has been created, so you can pass it to paragon.getFieldOptions when loading options for dynamic inputs in this stage.

options

InputType[]

Show child properties

string

required

Use the input id as the key of the object you pass to paragon.setPostOptions. The value will be the input provided by the user.

type

enum

required

The type of this input, which will be one of the inputs in Input Types Reference.

title

string

required

The title to display to the user to describe this input.

subtitle

string

The descriptive text to display to the user to further describe or provide context to this input.

placeholder

string

The placeholder or example value to display to the user.

sourceType

string

The source type of this input, defined for dynamic enum inputs. This value can be passed to paragon.getFieldOptions to load the options for the input.See a walkthrough of implementing dynamic input types in Exposing User Settings.

required

boolean

Whether this input is required.

In the InstructionStage, the user should be shown instructional content with call-to-action buttons and a finish button to proceed to the next stage.

Example (Salesforce)

{
  "stage": "instruction",
  "content": "## Install Package\n\nPlease install the package using the link below.\n\n![Install Image](https://cdn.useparagon.com/image.png \"Install Image\")\n\nAfter installation, click the finish button.",
  "ctas": [
    {
      "type": "link",
      "label": "Install Package",
      "href": "https://example.com/package-install"
    },
    {
      "type": "copyButton",
      "label": "Copy link",
      "copyText": "https://example.com/package-install"
    }
  ],
  "finish": {
    "type": "finishButton",
    "label": "I've installed the package",
    "onClick": Function
  },
  "done": false
}

stage

const

"instruction" for InstructionStage.

content

string

required

Markdown-formatted content to display to the user. This can include headings, images, and other markdown elements.

ctas

CTA[]

An array of call-to-action buttons to display alongside the content. Each CTA can be either a link or a copy button.

Show child properties

Link
CopyButton

type

const

required

"link" for Link CTAs.

label

string

required

The text to display on the link button.

href

string

required

The URL to navigate to when the link is clicked.

type

const

required

"copyButton" for CopyButton CTAs.

label

string

required

The text to display on the copy button.

copyText

string

required

The text to copy to the clipboard when the button is clicked.

finish

FinishButton

required

The finish button that the user clicks to proceed to the next stage after completing the instructions.

Show child properties

type

const

required

"finishButton" for FinishButton.

label

string

required

The text to display on the finish button.

onClick

function

required

The callback function provided by the SDK to execute when the finish button is clicked. When this button is clicked, call finish.onClick() to mark the instruction stage as complete.

.installFlow.start

Call paragon.installFlow.start to begin an install flow for an integration. See an example call.

JavaScript

paragon.installFlow.start(integrationType, options);

Arguments:

integrationType

string

required

The integration type string, like salesforce.

options

object

required

Hide child properties

onNext(nextStage)

function

This callback is called when the install flow is ready to move to the next stage.Your app must render the appropriate UI for each stage, so that your user can provide the necessary details in that stage to connect their account.

Show callback arguments

nextStage

InstallFlowStage

The install flow stage for your app to render. See InstallFlowStage for more details.

onComplete()

function

This callback is called when the install flow completes successfully.

onError(error, context)

function

This callback is called when the install flow fails, with an error object and error context.

Show callback arguments

error

Error

The error object. You can read the .name of the error object to identify one of the following error types:

OAuthBlockedError: The browser blocked the OAuth prompt from appearing. This may require the user to allow popups in their browser settings.
OAuthTimeoutError: The OAuth prompt took longer than oauthTimeout milliseconds (as provided in options) to complete.
UserNotAuthenticatedError: The user is not authenticated with the Paragon SDK. Verify that paragon.authenticate has been called before starting the install flow.
NoActiveInstallFlowError: An install flow function was called, but no install flow is currently active. Call paragon.installFlow.start to start an install flow.
HeadlessModeNotEnabledError: Headless Connect Portal is not enabled. Call paragon.setHeadless to enable Headless mode.
IntegrationNotFoundError: The provided integration type is not found or has not been enabled in your Paragon project.

context

ErrorContext | null

The error context object.

Show child properties

stage

InstallFlowStage

The stage that the install flow was on when the error occurred.One of: accountType, preOptions, postOptions, instruction.

oauthTimeout

number

The number of milliseconds to wait for an OAuth prompt to complete. If the user does not complete the OAuth prompt within this time, the install flow will fail, and the onError callback will be called.If not provided, there will be no timeout for the OAuth prompt.

allowMultipleCredentials

boolean

Set to true if using Multi-Account Authorization. This will allow users to connect multiple accounts under one integration type.Defaults to false.

selectedCredentialId

string

Set this parameter to replace an account by a selected Credential ID instead of connecting a new account.This can be used to prompt a user to reconnect a credential if authorization has been revoked and the status of the credential is INVALID.

overrideRedirectUrl

string

Set this parameter to your Redirect Page URL for integrations like Google Drive.

.installFlow.setAccountType

Call paragon.installFlow.setAccountType when the user selects an account type in the AccountTypeStage.

JavaScript

paragon.installFlow.setAccountType(accountType);

Arguments:

accountType

string

required

The account type to set. This should be the id property of the Account Type option that the user selected.

.installFlow.setPreOptions

Call paragon.installFlow.setPreOptions when the user finishes providing inputs in the PreOptionsStage.

JavaScript

await paragon.installFlow.setPreOptions(values);

This returns a Promise that resolves when the values are saved. Upon success, the install flow will move to the next stage and call onNext. If there is no stage after the PreOptionsStage, the install flow will call onComplete. Arguments:

values

object

required

The values to set for the inputs in the PreOptionsStage.This should be an object, where the keys are ids of the inputs in the PreOptionsStage, and the values are the values that the user provided for each input.

Example (Shopify)

{
  "SHOP_NAME": "my-shop"
}

.installFlow.setPostOptions

Call paragon.installFlow.setPostOptions when the user finishes providing inputs in the PostOptionsStage.

JavaScript

await paragon.installFlow.setPostOptions(values);

This returns a Promise that resolves when the values are saved. Upon success, the install flow will be completed and call onComplete. Arguments:

values

object

required

The values to set for the inputs in the PostOptionsStage.This should be an object, where the keys are ids of the inputs in the PostOptionsStage, and the values are the values that the user provided for each input.

Example (Jira)

{
  "JIRA_CLOUD_ID": "my-jira-cloud-id"
}

.installFlow.cancel

Call paragon.installFlow.cancel if your user abandons the integration connection process during an active install flow. This function resets the state for paragon.installFlow to begin again at another time.

JavaScript

paragon.installFlow.cancel();

If your user has completed an OAuth connection but has not completed required post-OAuth options, this function will remove the credential with status "PENDING" automatically by calling paragon.uninstallIntegration.However, if the page has been refreshed or the SDK has been reloaded since the pending credential was connected, you will need to call paragon.uninstallIntegration manually to disconnect the pending credential from your user.

External File Picker

You can use the Paragon SDK to allow your user to select files from a File Storage integration in your app. The SDK provides an ExternalFilePicker class to load any necessary JavaScript dependencies into your page and authenticate with your user’s connected account. Supported integrations for ExternalFilePicker:

.ExternalFilePicker

Construct a new instance of an ExternalFilePicker for an integration given by integrationType. Any required JS dependencies do not start loading until picker.init is called.

JavaScript

const picker = new paragon.ExternalFilePicker(integrationType, options);

Arguments:

integrationType

string

required

Type of integration (i.e. “googledrive”, “onedrive”, “sharepoint”, “box”)

options

object

Show Optional options

allowedTypes

string[]

An array of MIME types to allow for file selection, e.g. ["application/pdf", "image/jpeg"]. If undefined, all types will be allowed.

allowMultiSelect

boolean

If true, allow multiple files to be selected. Default: false.

allowFolderSelect

boolean

If true, allow folders to be selected. Default: false.

onOpen

function

Called when a Picker successfully appears in the app.

onClose

function

Called when a Picker gets closed.

onFileSelect

function

Called when a Picker file selection is made. files is an Array of objects with the selected file objects from the 3rd-party picker script.

onCancel

function

Called when a Picker gets closed without any files selected.

Example:

JavaScript

const picker = new paragon.ExternalFilePicker("googledrive", {
  allowedTypes: ["application/pdf"],
  allowMultiSelect: false,
  onFileSelect(files) {
    console.log("User picked files", files);
  },
});

picker.init

Initialize a file picker with required configuration initConfig. Required configuration varies per integration; see integration-specific documentation for specific details. This function loads required JS dependencies into the page, if they have not already been loaded. Other methods, like picker.open and picker.getInstance, cannot be called until the Promise returned by picker.init is resolved.

JavaScript

await picker.init(initConfig);

Arguments:

initConfig

object

required

Show child properties

developerKey

string

The developer key required for certain integrations (e.g., Google Drive).

selectedCredentialId

string

Pass to select a specific account to pick files from when using Multi-Account Authorization.

siteUrl

string

SharePoint only. Optional site URL override (e.g. https://contoso.sharepoint.com/sites/MySite). Takes precedence over siteId and the connected credential’s default site. See SharePoint File Picker for details.

siteId

string

SharePoint only. Optional site ID (e.g. contoso.sharepoint.com,191d8a17-...). Resolved to a site URL via Microsoft Graph before opening the picker. Ignored when siteUrl is also provided.

Example:

JavaScript

await picker.init({
  developerKey: "AIzaS...",
});

picker.open

Presents the file picker in your app. Selected files or other events will be received in the callbacks you specified in the constructor.

JavaScript

picker.open();

picker.getInstance

Returns a reference to the third-party JS library object that this file picker is using. This object can be used for additional integration-specific customization.

JavaScript

const instance = picker.getInstance();

​SDK Methods

​.authenticate

​.connect

Multi Account Authorization

​.subscribe

​.installIntegration

​.uninstallIntegration

​.getIntegrationMetadata

​.getIntegrationConfig

​.getUser

​.setUserMetadata

​.updateIntegrationUserSettings

​.getDataSourceOptions

​.getFieldOptions

​.getSourcesForInput

​.setDataSources

​.enableWorkflow

​.disableWorkflow

​.updateWorkflowState

​.updateWorkflowUserSettings

​.getCustomWebhookUserManualUrl

​.workflow

​.request

​.event

​.setHeadless

​API Only

​GET project’s integrations

​GET user’s Connect credentials

​UPDATE user’s Connect credential

​Headless Connect installFlow

​.installFlow.start

​.installFlow.setAccountType

​.installFlow.setPreOptions

​.installFlow.setPostOptions

​.installFlow.cancel

​External File Picker

​.ExternalFilePicker

​picker.init

​picker.open

​picker.getInstance

SDK Methods

.authenticate

.connect

.subscribe

.installIntegration

.uninstallIntegration

.getIntegrationMetadata

.getIntegrationConfig

.getUser

.setUserMetadata

.updateIntegrationUserSettings

.getDataSourceOptions

.getFieldOptions

.getSourcesForInput

.setDataSources

.enableWorkflow

.disableWorkflow

.updateWorkflowState

.updateWorkflowUserSettings

.getCustomWebhookUserManualUrl

.workflow

.request

.event

.setHeadless

API Only

`GET` project’s integrations

`GET` user’s Connect credentials

`UPDATE` user’s Connect credential

Headless Connect installFlow

.installFlow.start

.installFlow.setAccountType

.installFlow.setPreOptions

.installFlow.setPostOptions

.installFlow.cancel

External File Picker

.ExternalFilePicker

picker.init

picker.open

picker.getInstance