API Reference

Paragon SDK Functions

Below are all the public functions exposed on the Paragon SDK global, accessible at window.paragon (or paragon).

.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
JavaScript SDK
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().

.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
JavaScript SDK
paragon.connect("salesforce");

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
JavaScript SDK
paragon.getUser();
// 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.

.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
JavaScript SDK
var eventName = "Contact Created";
var eventPayload = { "name": "Brandon", "email": "b@useparagon.com" };
// Called once during your user's session
paragon.authenticate("project-id", <Paragon User Token>);
// Trigger the "Contact Created" App Event
paragon.event(eventName, eventPayload);
REST API
// 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": "b@useparagon.com"
}
}

When sending live events from your application, Paragon will not validate that your event payload matches the defined event schema.

.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
JavaScript SDK
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 :)