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.

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.

​

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

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.

​

.getUser() → ParagonUser

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

A ParagonUser is an object shaped like:

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.

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.

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.

​

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

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:" 
}

​

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 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",
  "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"
}]

​

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.

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"
}]

​

Addendum: Building the ParagonUser object

With the two responses that are provided above, you can rebuild the ParagonUser with a transformation that looks like:

const integrations = await fetch(...);
const credentials = await fetch(...);
​
const user = {};
​
integrations.forEach((integration) => {
  if (integration.configs.length) {
    user.integrations[integration.type] = {
			// Default state for each integration
      enabled: false,
      configuredWorkflows: {},
    };
  }
});
credentials.forEach((credential) => {
  const { type } = integrations.find(
    (integration: IConnectIntegration) => integration.id === credential.integrationId,
  );
  user.integrations[type] = {
		// Saved state for each integration
    ...credential.config,
    enabled: true,
    credentialId: credential.id,
  };
});