SDK / API Reference
Below are all the public functions exposed on the Paragon SDK global, accessible at
window.paragon, and/or the Paragon REST API.
.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 SDK
await paragon.authenticate(
// You can find your project ID in the Overview tab of any Integration
"38b1f170-0c43-4eae-9a04-ab85325d99f7",
// See Setup for how to encode your user token
"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ey..."
);
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.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.JavaScript SDK
paragon.connect("salesforce", {
onSuccess: (event) => {},
onError: (event) => {}
});
- onSuccess - the callback that is invoked when an integration is successfully enabled
- onError - the callback that is invoked if an unexpected error occurs
You must have an integration configured of this
integrationType for the Portal to appear. Otherwise, this function does nothing.Call
.disableWorkflow to turn off a workflow for a user by ID.JavaScript SDK
REST API
paragon.disableWorkflow("<Workflow ID>");
Request
DELETE https://api.useparagon.com/projects/<Project ID>/sdk/workflows/<Workflow ID>
Authorization: Bearer <Paragon User Token>
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!JavaScript SDK
REST API
paragon.getIntegrationMetadata();
// Response
{
[
{
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'
}
]
}
GET https://api.useparagon.com/projects/<Paragon Project ID>/sdk/metadata
Authorization: Bearer <Paragon User Token>
Content-Type: application/json
// Response
{
[
{
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'
}
]
}
Call
.getUser to retrieve the currently authenticated user and their connected integration state.A ParagonUser is an object shaped like:
JavaScript SDK
REST API
paragon.getUser();
// Response
{
authenticated: true,
userId: "xyz", // The user ID you specified in the signed JWT
integrations: {
salesforce: {
enabled: true
},
shopify: {
enabled: false
}
}
}
GET https://api.useparagon.com/projects/<Paragon Project ID>/sdk/me
Authorization: Bearer <Paragon User Token>
Content-Type: application/json
// Response
{
authenticated: true,
userId: "xyz", // The user ID you specified in the signed JWT
integrations: {
salesforce: {
enabled: true
},
shopify: {
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.
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.
JavaScript SDK
REST API
var eventName = "Contact Created";
var eventPayload = { "name": "Brandon", "email": "[email protected]" };
// Called once during your user's session
paragon.authenticate("project-id", <Paragon User Token>);
// Trigger the "Contact Created" App Event
paragon.event(eventName, eventPayload);
// Trigger the "Contact Created" App Event
POST https://api.useparagon.com/projects/<Paragon Project ID>/sdk/events/trigger
// Headers
Authorization: Bearer <Paragon User Token>
Content-Type: application/json
// Body
{
"name": "Contact Created",
"payload": {
"name": "Brandon",
"email": "[email protected]"
}
}
When sending live events from your application, Paragon will not validate that your event payload matches the defined event schema.
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.
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.
JavaScript SDK
paragon.installIntegration("googledrive");
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.
Call
.subscribe to subscribe to different events and changes from the Paragon SDK. You can find the possible eventNamesbelow:Event Type | Usage in .subscribe() | Usage in .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
.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.
Integration Enabled / Disabled
Workflow State Changed
Connect Portal Opened / Closed
type IntegrationUninstallEvent = {
integrationId: string;
integrationType: VisibleConnectAction;
};
// Using global subscribe
paragon.subscribe(
"onIntegrationUninstall",
(event: IntegrationUninstallEvent, 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.Integration Enabled / Disabled
Workflow State Changed
Connect Portal Opened / Closed
type IntegrationUninstallEvent = {
integrationId: string;
integrationType: VisibleConnectAction;
};
// Using local call to paragon.connect
paragon.connect("<integration>", {
onSuccess: {/* ... */},
onError: {/* ... */},
onUninstall: (event: IntegrationUninstallEvent, 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) => {/* ... */}
});
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.
JavaScript SDK
REST API
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://api.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:"
}
Call
.setUserMetadata() to associate the authenticated user with metadata from your application. This metadata can be accessed with .getUser() or retrieved over the API.JavaScript SDK
REST API
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" } }
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.
JavaScript SDK
REST API
// Use the integration name, as used in paragon.connect();
await paragon.uninstallIntegration("salesforce");
Get the ID of the integration you want to disconnect, with the
/sdk/integrations endpoint:Request
GET https://api.useparagon.com/projects/<Project ID>/sdk/integrations
// Headers
Authorization: Bearer <Paragon User Token>
Response
[
{ "id": "<Integration ID>", "type": "salesforce", ... },
{...}
]
The
<Integration ID> can be used to disconnect the integration for the user:Request
DELETE https://api.useparagon.com/projects/<Project ID>/sdk/integrations/<Integration ID>
// Headers
Authorization: Bearer <Paragon User Token>
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.JavaScript SDK
REST API
// Called once during your user's session
paragon.authenticate("project-id", <Paragon User Token>)
// Trigger the "Lead Created" workflow
await paragon.workflow("<workflow_id>", {
"body": {
"email": "[email protected]",
"first_name": "Bowie",
"last_name": "Foo"
}
});
// Trigger the "Lead Created" Workflow
POST https://api.useparagon.com/projects/<Paragon Project ID>/sdk/triggers/<Workflow ID>
Authorization: Bearer <Paragon User Token>
Content-Type: application/json
{
"email": "[email protected]",
"first_name": "Bowie",
"last_name": "Foo
}
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.
REST API
GET https://api.useparagon.com/projects/<Paragon Project ID>/sdk/integrations
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",
"type": "slack",
"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"
}]
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.
REST API
GET https://api.useparagon.com/projects/<Paragon 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"
}]
Last modified 22d ago