Working with Connections

Creating a Connection

You'll typically create a new connection from the Plugins page. Follow these steps to create a connection:

1. From the Space Console, click Plugins. This will bring you to the Connections tab.
2. Click New Connection.
3. From the New Connection modal, click HTTP.

   ℹ️

   At the moment, Integrator only supports HTTP connections. Other connection methods are currently in development.

4. Fill out the connection as described in the HTTP Connections section below.
5. When finished, click Create Connection.

You can also create connections on the fly in the Form Builder and the Workflow Builder.

HTTP Connections

Integrator currently supports only HTTP connections. Other connection types are currently in development.

When creating an HTTP connection, you can specify the following information:

• Connection Name: Required. A friendly name for the connection.

• API Documentation Link: The address of any additional documentation explaining the purpose or functions of the API endpoint.

• Description: A description of the connection.

• Base URL: Required. The base location of the API endpoint.

• Test Path: A health check endpoint (e.g., /health or /api/v1/version) that confirms connectivity and endpoint health.

• Set Trusted CA Certificate: Indicates whether the connection requires a trusted custom authority. This only applies to HTTPS connections.

• Authentication: The method used to authenticate with the connection. Depending on the authentication method selected, additional options will be displayed. Choose the option that matches the requirement of integrated system.

  • None: Requires no additional input.

  • Basic Auth: A widely used authentication method where the client provides a username and password.

    Field Name	Required
    Username	Yes
    Password	No

  • HTTP Bearer Token: A token-based authentication method where the client retrieves a token from the external system and includes it in the Authorization header of subsequent requests. This method is flexible, supporting advanced configurations for token retrieval.

    Field Name	Required
    Token Header (default: Authorization)	Yes
    Token Prefix (default: Bearer)	Yes
    Method (default: POST)	Yes
    Request Path	Yes

    Authentication Request Inputs:

    URL Parameters

    You can enter hard-coded information to pass in the fields that accept parameter values, or you can use the {{parameter}} format to create dynamic parameters. When you run a test with a dynamic parameter, you'll be prompted to enter a parameter value.

    Headers

    HTTP headers let you pass additional header information, such as content-type, along with an HTTP request.

    Body

    You can send body content with your authentication operation using one of the following formats:

    • Form URL Encoded: Sends the body content encoded as a query string (for example, key1=value1&key2=value2). All characters must be URL encoded.
    • Raw: Sends the query string in JSON format

    Outputs Required.

    • Token: Provide a JavaScript express that maps to the response of the token value (for example, body['access_token'])
    • Expiration: Provide a JavaScript express that maps to a numeric expiration value in seconds (for example, body['expires_in'])

    Secrets

    Allows you to define sensitive values which can be used with the {{secretKey}} format to securely inject the sensitive values into connection configurations.

    Advanced

    The Advanced tab lets you configure the operation's redirect, response streaming behavior and identify a different authentication URL.

    • Follow Redirect: Select this option to automatically follow HTTP redirections when the operation returns a 3xx response.

    • Stream Response: Select this option to configure the operation to send updates when an event happens.

    • Use different connection for auth: Select this option to configure a Token Base URL (required) and optionally a Token Trusted CA Certificate.

      

  • Raw BearerToken: A simpler variant of Bearer Token authentication where the user manually provides a pre-generated token. This method is used for scenarios where token generation is managed externally.

    Field Name	Required
    Token Header (default: Authorization)	Yes
    Token Prefix (default: Bearer)	Yes
    Token	No

  • OAuth 2.0: An industry-standard protocol for token-based authentication and authorization.

    Field Name	Required?
    Access Token URL	Yes
    Client ID	Yes
    Client Secret	No
    Client Auth	Yes
    Scope	No
    Trusted CA Certificate	No

Editing a Connection

Once a connection has been created, it can only be modified from the Plugins > Connections window. Follow these steps to edit a connection:

1. Click the connection you want to edit.
2. From the Actions menu, select Edit.
3. Make the necessary changes.
4. Click Update Connection.