API Reference

Search…
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.
​
.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.
JavaScript SDK
1
paragon.authenticate(
2
	// You can find your project ID in the Overview tab of any Integration
3
	"38b1f170-0c43-4eae-9a04-ab85325d99f7",
4
​
5
	// See Setup for how to encode your user token
6
	"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ey..."
7
);
Copied!
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)
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
1
paragon.connect("salesforce", {
2
    onSuccess: (event) => {},
3
    onError: (event) => {}
4
});
Copied!
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.
​
.getUser() → ParagonUser
Call .getUser to retrieve the currently authenticated user and their connected integration state.
A ParagonUser is an object shaped like:
JavaScript SDK
1
paragon.getUser();
2
​
3
// Response
4
{
5
	authenticated: true,
6
	userId: "xyz", // The user ID you specified in the signed JWT
7
	integrations: {
8
		salesforce: {
9
			enabled: true
10
		},
11
		shopify: {
12
			enabled: false
13
		}
14
	}
15
}
Copied!
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.
This method is currently only available via the SDK. To access user information via the REST API, see the Get project's integration and Get user's Connect credentials API methods.
​
.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.
JavaScript SDK
REST API
1
var eventName = "Contact Created";
2
var eventPayload = { "name": "Brandon", "email": "[email protected]" };
3
​
4
// Called once during your user's session 
5
paragon.authenticate("project-id", <Paragon User Token>);
6
​
7
// Trigger the "Contact Created" App Event
8
paragon.event(eventName, eventPayload);
Copied!
1
// Trigger the "Contact Created" App Event
2
POST https://api.useparagon.com/projects/<Paragon Project ID>/sdk/events/trigger
3
​
4
// Headers
5
Authorization: Bearer <Paragon User Token>
6
Content-Type: application/json
7
​
8
// Body
9
{ 
10
    "name": "Contact Created", 
11
    "payload": { 
12
        "name": "Brandon", 
13
        "email": "[email protected]" 
14
    }
15
}
Copied!
When sending live events from your application, Paragon will not validate that your event payload matches the defined event schema.
​
.subscribe(eventName: string, handler: Function)
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
1
type IntegrationUninstallEvent = {
2
  integrationId: string;
3
  integrationType: VisibleConnectAction;
4
};
5
​
6
// Using global subscribe
7
paragon.subscribe(
8
  "onIntegrationUninstall",
9
  (event: IntegrationUninstallEvent, user: AuthenticatedConnectUser) => { /* ... */ }
10
);
Copied!
1
type WorkflowStateChangeEvent = {
2
  integrationId: string;
3
  workflowId: string;
4
};
5
​
6
// Using global subscribe
7
paragon.subscribe(
8
  "onWorkflowChange",
9
  (event: WorkflowStateChangeEvent, user: AuthenticatedConnectUser) => { /* ... */ }
10
);
Copied!
1
type PortalOpenEvent = {
2
  integrationId: string;
3
  integrationType: VisibleConnectAction;
4
};
5
​
6
type PortalCloseEvent = {
7
  integrationId: string;
8
  integrationType: VisibleConnectAction;
9
};
10
​
11
// Using global subscribe
12
paragon.subscribe(
13
  "onPortalOpen",
14
  (event: PortalOpenEvent, user: AuthenticatedConnectUser) => { /* ... */ }
15
);
16
paragon.subscribe(
17
  "onPortalClose",
18
  (event: PortalCloseEvent, user: AuthenticatedConnectUser) => { /* ... */ }
19
);
Copied!
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
1
type IntegrationUninstallEvent = {
2
  integrationId: string;
3
  integrationType: VisibleConnectAction;
4
};
5
​
6
// Using local call to paragon.connect
7
paragon.connect("<integration>", {
8
  onSuccess: {/* ... */},
9
  onError: {/* ... */},
10
  onUninstall: (event: IntegrationUninstallEvent, user: AuthenticatedConnectUser) => { /* ... */ }
11
});
Copied!
1
type WorkflowStateChangeEvent = {
2
  integrationId: string;
3
  workflowId: string;
4
};
5
​
6
// Using local call to paragon.connect
7
paragon.connect("<integration>", {
8
  onWorkflowChange: (event: WorkflowStateChangeEvent, user: AuthenticatedConnectUser) => {/* ... */}
9
});
Copied!
1
type PortalOpenEvent = {
2
  integrationId: string;
3
  integrationType: VisibleConnectAction;
4
};
5
​
6
type PortalCloseEvent = {
7
  integrationId: string;
8
  integrationType: VisibleConnectAction;
9
};
10
​
11
// Using local call to paragon.connect
12
paragon.connect("<integration>", {
13
  onOpen: (event: PortalOpenEvent, user: AuthenticatedConnectUser) => {/* ... */},
14
  onClose: (event: PortalCloseEvent, user: AuthenticatedConnectUser) => {/* ... */}
15
});
Copied!
.request(integrationType: string, path: string, requestOptions: RequestInit ) → Promise<unknown>
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
1
await paragon.request('slack', '/chat.postMessage', {
2
	method: 'POST',
3
	body: {
4
		channel: 'CXXXXXXX0' // Channel ID,
5
		text: 'This message was sent with Paragon Connect :exploding_head:'
6
	}
7
});
8
​
9
// -> Responds with { ok: true }, and sends a message :)
Copied!
1
POST https://api.useparagon.com/projects/<Paragon Project ID>/sdk/proxy/slack/chat.postMessage
2
​
3
Authorization: Bearer <Paragon User Token>
4
Content-Type: application/json
5
​
6
{ 
7
    "channel": "CXXXXXXX0", 
8
    "text": "This message was sent with Paragon Connect :exploding_head:" 
9
}
Copied!
​
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.
REST API
1
GET https://api.useparagon.com/projects/<Paragon Project ID>/sdk/integrations
2
​
3
Authorization: Bearer <Paragon User Token>
4
Content-Type: application/json
5
​
6
// Example response (may include more than is in this list):
7
​
8
[{
9
  "id": "00da4146-7ac4-4253-a8f7-96849b8137d9",
10
  "dateCreated": "2021-03-24T12:19:21.511Z",
11
  "dateUpdated": "2021-03-24T12:19:28.512Z",
12
  "dateDeleted": null,
13
  "projectId": "db06d291-ba2c-41c5-9a12-9362abfd6228",
14
  "integrationId": "95bedc9f-6a22-4855-b08d-e68dc073ad91",
15
  "personaId": "0563109f-5e71-46c5-8483-1ac8c0913d6c",
16
  "config": {
17
    "configuredWorkflows": {
18
      "3eb95154-3c7b-413c-bf14-ba367d95b53f": {
19
        "enabled": true,
20
        "settings": {
21
					"example-input-id": "example value"
22
				}
23
      }
24
    }
25
  },
26
  "isPreviewCredential": false,
27
  "providerId": "50150244515"
28
}]
Copied!
​
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.
REST API
1
GET https://api.useparagon.com/projects/<Paragon Project ID>/sdk/credentials
2
​
3
Authorization: Bearer <Paragon User Token>
4
Content-Type: application/json
5
​
6
// Example response (may include more than is in this list):
7
​
8
[{
9
  "id": "00da4146-7ac4-4253-a8f7-96849b8137d9",
10
  "dateCreated": "2021-03-24T12:19:21.511Z",
11
  "dateUpdated": "2021-03-24T12:19:28.512Z",
12
  "dateDeleted": null,
13
  "projectId": "db06d291-ba2c-41c5-9a12-9362abfd6228",
14
  "integrationId": "95bedc9f-6a22-4855-b08d-e68dc073ad91",
15
  "personaId": "0563109f-5e71-46c5-8483-1ac8c0913d6c",
16
  "config": {
17
    "configuredWorkflows": {
18
      "3eb95154-3c7b-413c-bf14-ba367d95b53f": {
19
        "enabled": true,
20
        "settings": {
21
					"example-input-id": "example value"
22
				}
23
      }
24
    }
25
  },
26
  "isPreviewCredential": false,
27
  "providerId": "50150244515"
28
}]
Copied!
​
Addendum: Building the ParagonUser object
With the two responses that are provided above, you can rebuild the ParagonUser with a transformation that looks like:
1
const integrations = await fetch(...);
2
const credentials = await fetch(...);
3
​
4
const user = {};
5
​
6
integrations.forEach((integration) => {
7
  if (integration.configs.length) {
8
    user.integrations[integration.type] = {
9
			// Default state for each integration
10
      enabled: false,
11
      configuredWorkflows: {},
12
    };
13
  }
14
});
15
credentials.forEach((credential) => {
16
  const { type } = integrations.find(
17
    (integration: IConnectIntegration) => integration.id === credential.integrationId,
18
  );
19
  user.integrations[type] = {
20
		// Saved state for each integration
21
    ...credential.config,
22
    enabled: true,
23
    credentialId: credential.id,
24
  };
25
});
Copied!