Skip to main content
Multiple Account Authorizations is a set of SDK options that allows Connected Users to connect multiple accounts for the same integration. For example, a Connected User can connect multiple Google Drive accounts, with each account stored as a separate Credential.

​
Supported Products

ProductSupported
WorkflowsYes
ActionKitYes (via X-Paragon-Credential header)
Managed SyncYes (via credentialId in request body)
Proxy APIYes (via selectedCredentialId or X-Paragon-Credential)

​
Getting Started

Connecting new accounts To get started with Multiple Account Authorizations, you can pass in allowMultipleCredentials to paragon.installIntegration: 
// Connect a new Google Calendar account
paragon.installIntegration("googleCalendar", {
    allowMultipleCredentials: true,

    // Set to true to show User Settings after installation:
    showPortalAfterInstall: true
});
This function starts the connection process for a new account of an integration. After the user has connected, you can optionally show the Connect Portal to present any User Settings that are used to configure the integration. Listing accounts Your UI must be able to render a list of each account your user has connected for an integration. Use paragon.getUser to retrieve this list: 
const user = paragon.getUser();

// An array of all Google Calendar accounts the user has connected:
user.integrations.googleCalendar.allCredentials;
Each account (“credential”) will have an ID that can be used to present the Connect Portal for the account, remove the account, or route requests to the account. Use paragon.subscribe to listen for change events to the Paragon user object, if your UI updates dynamically. Managing existing accounts You can allow your users to manage User Settings for a specific account using the Connect Portal by passing selectedCredentialId to paragon.connect: 
// Modify User Settings for an existing Google Calendar account
paragon.connect("googleCalendar", {
    selectedCredentialId: "a5e995c2-7709-43fd-9cdf-f759faa52497"
});
Removing existing accounts You can disconnect an existing account by passing selectedCredentialId to paragon.uninstallIntegration: 
// Disconnect an existing Google Calendar account
paragon.uninstallIntegration("googleCalendar", {
    selectedCredentialId: "a5e995c2-7709-43fd-9cdf-f759faa52497"
});

​
Usage

A subset of SDK functions can be passed an additional parameter for Multiple Account Authorizations, as outlined below. In general, to use Multiple Account Authorizations, you will need to: App Events and Workflows do not need to be updated to support Multiple Account Authorizations.

​
Access Control

If you are using Multi-Account Authorization to enable multiple users within one organization to connect their individual credentials within one Connected User, use JWT Permissions to restrict each user’s access to only the accounts they have connected:

JWT Permissions

Learn more about implementing JWT Permissions to control access to credentials.

​
Reference

​
.connect

With Multiple Account Authorizations, use paragon.connect to present the Connect Portal for an existing account for the intended integration. Use paragon.installIntegration to connect new accounts.
  • The Connect Portal can show the settings and workflows enabled for one account at a time, set by the selectedCredentialId property. If selectedCredentialId is not defined, the Connect Portal will use the first account available.
  • When the Connect Portal appears, a user can enable or disable workflows, update User Settings, and disconnect the account that is selected.
For full documentation of this method, see paragon.connect. Example:
JavaScript
// Connect a new account for this integration.
// NOTE: You must use `paragon.installIntegration` rather than `paragon.connect`.
paragon.installIntegration("salesforce", {
  allowMultipleCredentials: true
});

// Show the Connect Portal to configure an existing account for this integration.
paragon.connect("salesforce", {
  selectedCredentialId: "de06dea8-8680-483c-95ea-cfcf66582c96"
});

​
.installIntegration

The paragon.installIntegration function starts the connection process for a new account of an integration. With Multiple Account Authorizations, pass allowMultipleCredentials: true so the function does not throw an error if the user already has this integration installed. You can use the resulting Promise to get the newly created credential. For full documentation of this method, see paragon.installIntegration. Example: 
const { credential } = await paragon.installIntegration("googledrive", {
  allowMultipleCredentials: true
});

​
.uninstallIntegration

Call paragon.uninstallIntegration to disconnect an integration for the authenticated user. With Multiple Account Authorizations, use selectedCredentialId (SDK) or the X-Paragon-Credential header (API) to select a specific account to disconnect. For full documentation of this method, see paragon.uninstallIntegration. Example: 
paragon.uninstallIntegration("googledrive", {
  selectedCredentialId: "de06dea8-8680-483c-95ea-cfcf66582c96"
});

​
.getUser

Call paragon.getUser to retrieve the currently authenticated user and their connected integration state. With Multiple Account Authorizations, paragon.getUser additionally returns allCredentials, an array of connected accounts for a given integration. For full documentation of this method, see paragon.getUser. Example Response:
JavaScript
{
  authenticated: true,
  userId: "xyz", // The user ID you specified in the signed JWT
  integrations: {
    salesforce: {
      enabled: true,
      allCredentials: [
        {
          id: "a5e995c2-7709-43fd-9cdf-f759faa52497",
          dateCreated: "2023-05-30T22:33:20.349Z",
          dateUpdated: "2023-05-30T22:33:20.349Z",
          projectId: "d1f142cd-1dfe-4d76-ab4c-8f64901a9c5c",
          integrationId: "8aaad9ff-5adb-433c-a17b-da093f9d4528",
          personaId: "30975f6a-c50c-4e74-914a-3eb700db8b05",
          config: { configuredWorkflows: {} },
          isPreviewCredential: false,
          providerId: "1223115691",
          providerData: {},
          status: "VALID",
          dateRefreshed: "2023-05-30T22:33:20.349Z",
          dateValidUntil: "2023-05-30T23:33:17.809Z",
          refreshFailureCount: 0,
          isRefreshing: false,
          externalId: "my-external-id", // Present if set via .connect() or .installIntegration()
        },
      ],
      configuredWorkflows: {},
      credentialId: "a5e995c2-7709-43fd-9cdf-f759faa52497",
      credentialStatus: "VALID",
      providerId: "1223115691",
      providerData: {},
    },
    shopify: {
      enabled: false,
    },
  },
}

​
.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. With Multiple Account Authorizations, use selectedCredentialId (SDK) or the X-Paragon-Credential header (API) to select a specific account for which to trigger a workflow. The Credential ID that is used will be recorded for viewing in the Monitoring Workflows page. For full documentation of this method, see paragon.workflow. Example: 
// Trigger the "Lead Created" workflow
await paragon.workflow("<workflow_id>", {
  body: {
    "email": "bowie@useparagon.com",
    "first_name": "Bowie",
    "last_name": "Foo"
  },
  selectedCredentialId: "de06dea8-8680-483c-95ea-cfcf66582c96"
});

​
.request

Call paragon.request to send an API request to a third-party integration on behalf of one of your users. With Multiple Account Authorizations, use selectedCredentialId (SDK) or the X-Paragon-Credential header (API) to select a specific account to use with the Proxy API or ActionKit. For full documentation of this method, see paragon.request. Example: 
await paragon.request('slack', '/chat.postMessage', {
  method: 'POST',
  body: {
    channel: 'CXXXXXXX0', // Channel ID
    text: 'This message was sent with Paragon Connect :exploding_head:'
  },
  selectedCredentialId: "de06dea8-8680-483c-95ea-cfcf66582c96"
});

​
picker.init

You can use the Paragon SDK to allow your user to select files from a File Storage integration in your app. After constructing a new instance of the ExternalFilePicker, you can initialize a file picker with the required configuration initConfig, including the selectedCredentialId for the user. 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. Example:
JavaScript
await picker.init({
  developerKey: "AIzaS...",
  appId: "457...",
  selectedCredentialId: "de06dea8-8680-483c-95ea-cfcf66582c96"
});