SDK / API Reference
Paragon SDK and API Methods
Below are all the public functions exposed on the Paragon SDK global, accessible at window.paragon
, and/or the Paragon REST API.
For on-premise/single-tenant users:
If you are using an on-prem/single-tenant instance of Paragon, you can call the .configureGlobal
function to point the SDK to use the base hostname of your Paragon instance.
.authenticate(projectId: string, userToken: string)
.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.
Once .authenticate
has been called, you can access the user's integration state with .getUser()
. .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(integrationType: string, installOptions?: InstallOptions)
Call .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.
This function must be called after the Paragon SDK has completed authentication. You can await
the Promise returned by #.authenticate-projectid-string-usertoken-string 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.
.disableWorkflow(workflowId: string) -> Promise
Call .disableWorkflow
to turn off a workflow for a user by ID.
.getIntegrationMetadata(integrationType: string?)
Call .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!
.getUser() → ParagonUser
Call .getUser
to retrieve the currently authenticated user and their connected integration state.
A ParagonUser is an object shaped like:
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.
.event(name: string, json: JSON)
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.
When sending live events from your application, Paragon will not validate that your event payload matches the defined event schema.
.installIntegration(integrationType: string, installOptions?: InstallOptions) -> Promise<void>
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 .connect
function.
The .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 rejects the returned Promise if the integration is already installed for the authenticated user.
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 #.connect-integrationtype-string-installoptions-installoptions.
.subscribe(eventName: string, handler: Function)
Call .subscribe
to subscribe to different events and changes from the Paragon SDK. You can find the possible eventNames
below:
Subscribing to SDK Events applies to all integrations globally. Specifying callbacks to .connect()
only applies to a currently open Connect Portal locally.
See the code examples below for how to subscribe to events using the Paragon SDK.
Alternatively, you can subscribe onOpen
, onClose
, onUninstall
, and onWorkflowChange
as a one-time event locally.
.request(integrationType: string, path: string, requestOptions: RequestInit ) → Promise
Call .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
, which takes three arguments:
integrationType
: 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
: 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
: Request options to include, such as:body
: An object representing JSON contents of the request.method
: An HTTP verb such as "GET" or "POST". Defaults to GET.
The function returns a promise for the request output, which will have a shape that varies depending on the integration and API endpoint.
.setUserMetadata(meta: object)
Call .setUserMetadata()
to associate the authenticated user with metadata from your application. This metadata can be accessed with .getUser()
or retrieved over the API.
.uninstallIntegration(integrationType: string) -> Promise
Call .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.
.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.
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
)The providerId is the authenticated user's ID assigned by their integration provider (e.g. for a Salesforce integration, this would would be the user's Salesforce user ID)
This method is currently available via REST API only.
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).
This method is currently available via REST API only.
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).
This method is currently available via REST API only.
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.
ExternalFilePicker
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:
new paragon.ExternalFilePicker(integrationType, options)
Construct a new instance of an ExternalFilePicker for an integration given by integrationType
. Any required JS dependencies do not start loading until .init
is called.
Example:
Options:
allowedTypes
(default:undefined
)An array of MIME types to allow for file selection, e.g.
["application/pdf", "image/jpeg"]
If
undefined
, all types will be allowed.
allowMultiSelect
(default:false
)If
true
, allow multiple files to be selected.
allowFolderSelect
(default:false
)If
true
, allow folders to be selected.
onOpen()
Called when a Picker successfully appears in the app.
onClose()
Called when a Picker gets closed.
onFileSelect(files)
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()
Called when a Picker gets closed without any files selected.
picker.init(initConfig)
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 .open
and .getInstance
, cannot be called until the Promise returned by .init
is resolved.
Example:
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.
Example:
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.
Last updated