Getting started with integrations

Integrations allow you to connect your Perygee organization to external services via an API. You can create your own integration or leverage an existing template from Perygee’s library, which includes a list of commonly used security products. We give you the tools so you can manage your data sources on your terms without relying on outside support.

Image


Creating a new integration
First, navigate to the admin console by clicking the “Admin console” text button from the left side panel or by clicking the Perygee logo in the top left. Then click “Integrations” from the left menu. If you’re already in the admin console, make sure “Integrations” is selected.

From there, click the “New integration” button in the top right. The integration will be created and the Integration Editor will open. Before configuring your integration, edit the name of the integration by clicking the placeholder name or pencil icon at the top.

Configuring an integration
From the Integration Editor, you can define the type of request that will be made to the external service. There are several pieces of information needed to properly configure the integration, which we will walk through in the sections that follow. Note that much of the terminology is shared with other similar tools such as Postman, a tool specifically created for defining requests.

Image and Description

image

The first configuration sections are used to provide general information about this integration. These details will be used elsewhere in the product (along with the name defined at the very top of the page) to refer to this integration.

Inputs

image

You can define inputs to make this request dynamic. Inputs are defined and referenced in the Integration Editor, but have values that are provided at a later time. For example, when you are using the integration in an import or from within an automation [insert link to automation + integration].

All inputs need a name and a value type. It’s a best practice to provide a description. A test value, if provided, will be used in place of the input when testing the request here in the Integration Editor.

Request URL

image

This is the web address to which we will send the HTTP request. You must also specify a HTTP request method (usually “GET” or “POST”). The web address input is a Liquid-compatible input that can reference input values using a special syntax.

Authorization

image

Many web APIs require authentication and authorization. Integrations can be authenticated with a Bearer Token or OAuth2.0 (client credentials). Selecting a type of authorization will prompt you for the necessary information. The requested fields should closely mirror the documentation provided by your API provider. All text inputs are Liquid-enabled.

Note that other types of header-based authentication can also be supported by using the Headers section to attach these values directly.

Params

image

Query or search params are sent along with a request in the URL. If your API requires these parameters, you can set the values in this section. Both the key and value inputs are Liquid-enabled.

Headers

image

Headers are sent along with the request and consist of key-value pairs. If your API requires headers to be sent, this section allows you to define the relevant values. Both the key and value inputs are Liquid-enabled.

Body

image

The request body can be in a JSON or Form-URLEncoded format. Documentation from your API should specify what content should be included in the body of the request.

Content-Type headers are added automatically depending on the chosen body type. All inputs are Liquid-enabled.

Once all necessary values are provided according to the specifications of the external API, you can test your integration by clicking “Send Request” and reviewing the retuned values.

Editing an integration
From the admin console, select “Integrations” from the menu on the left. Then click the name of the integration you want to edit to open the integration editing view. Make and save your changes.

Running an integration
There are two ways to run an integration:

  1. From the “Integrations” page in the admin console, click the “Run now” button next to the integration you want to run.
  2. Create an automation that will run the integration based on a triggering event or time interval.