Multiple Account Authorizations is a set of SDK options that enables you to connect multiple accounts of the same integration type for a Connected User.

For example, one Connected User can connect a Google Calendar integration for both their Google Workspace account and personal Google account.

​
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 for presenting 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:

  • Use user.integrations.[integration].allCredentials (a field returned in getUser) to display multiple connected accounts in your Integrations UI.
  • Update references to connect (or installIntegration and uninstallIntegration) to use the SDK with Multiple Account Authorizations enabled.
  • Update references to paragon.request and paragon.workflow (and API equivalents) to make sure that a specific account is targeted for a given integration type.

App Events and Workflows do not need to be updated to support Multiple Account Authorizations.

​
Reference

​
.getUser() -> ParagonUser

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

With Multiple Account Authorizations, the getUser() method additionally returns allCredentials, an array of connected accounts for a given integration.

paragon.getUser();

{
  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,
        },
      ],
      configuredWorkflows: {},
      credentialId: "a5e995c2-7709-43fd-9cdf-f759faa52497",
      credentialStatus: "VALID",
      providerId: "1223115691",
      providerData: {},
    },
    shopify: {
      enabled: false,
    },
  },
};

​
.installIntegration(integrationType: string, options?: IntegrationInstallOptions) -> Promise

You can use the resulting Promise to get the newly created credential.

JavaScript SDK
const { credential } = await paragon.installIntegration("googledrive", {
    allowMultipleCredentials: true
});

Replacing an account

You can replace one of your user’s existing connected accounts with the selectedCredentialId property. This option replaces the underlying connected account, keeping their enabled workflows and settings intact.

JavaScript SDK
paragon.installIntegration("googledrive", {
    allowMultipleCredentials: true,
    selectedCredentialId: "0d2cca60-268b-45f1-ac5e-af6aad403d8c"
});

​
.uninstallIntegration(integrationType: string, options?: IntegrationUninstallOptions) -> Promise

Call .uninstallIntegration() to disconnect an integration for the authenticated user.

paragon.uninstallIntegration("googledrive", {
    selectedCredentialId: "de06dea8-8680-483c-95ea-cfcf66582c96"
});

​
.connect(integrationType: string, options: IntegrationInstallOptions) -> Promise

With Multiple Account Authorizations, use .connect to present the Connect Portal for an existing account for the intended integration. .installIntegration is used 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.
JavaScript SDK
// Connect a new account for this integration.
// NOTE: You must use `.installIntegration` rather than `.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"
});

​
.request(integrationType: string, path: string, requestOptions: RequestOptions) → Promise

Call .request to send an API request to a third-party integration on behalf of one of your users.

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"
});

​
.workflow(workflowId: string, options: FetchOptions)

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

// Trigger the "Lead Created" workflow
await paragon.workflow("<workflow_id>", {
  body: {
    "email": "[email protected]",
    "first_name": "Bowie",
    "last_name": "Foo"
  },
  selectedCredentialId: "de06dea8-8680-483c-95ea-cfcf66582c96"
});