Connectors

Connectors describe how to authenticate in and interact with a specific External App.

Connector Definition

Connector spec is stored in the spec.yml file in the root of the connector.

Example:

name: Connector Name
logoUri: https://static.integration.app/connectors/connector-key/logo.png>
key: connector-key
parametersSchema:
  type: object
  properties:
	  parameter:
			type: string
appUuid: 877b0ad6-66b1-4d61-82f9-7e4d62acea69
auth:
  # The type of authentication
  type: client-credentials  # or oauth2, oauth1, proxy, membrane-token

  # User interface configuration
  ui:
    # Schema defining what inputs to request from users
    schema:
      type: object
      properties:
        apiKey:
          type: string
          title: "API Key"

    # Help URL with more information about the authentication
    helpUri: "https://docs.example.com/api-authentication"

  # Method implementations for different auth methods
  # These reference files in your connector directory
  makeApiClient:
    implementationType: mapping
  refreshCredentials:
    implementationType: javascript
  test:
    implementationType: javascript

  # Different authentication options/variants additionally to the default one
  options:
    option1:
      type: client-credentials
      title: "Option 1"
    option2:
      type: oauth2
      title: "Option 2"
      enabled:
         $var: connectorParameters.clientId # Only enable this option if clientId is provided in connector configuration.

It contains the following properties:

• name: Display name of the connector.
• key: Unique identifier for the connector.
• logoUri: URL to the connector's logo (should be publicly available)
• parametersSchema: Data Schema for connector parameters (see below)
• appUuid: UUID of an application in Pathfinder Universe.
• auth: describes how to authenticate in the external app - see below for details
  • type: one of the Authentication Types.
  • ui: definition of the connection user interface - see below for details.
  • List of Authentication Functions.
  • options: different ways to authenticate (if external app has them) - see below for details.

Authentication

Authentication is a part of the connector definition that specifies establishing connection to an external application:

• What information is needed from the user to establish the connection (and where to get it).
• How to use this information to get (and refresh) credentials.
• How to make API requests using the credentials.
• How to test if connection was successful.

User Interface

You can configure how connection UI looks like for your users and ask them for inputs you need to connect to the API.

In some cases, like standard oAuth authentication, you don't need to ask users for anything, and you can skip configuring the UI.

You can configure the following:

• Description - short description of what is happening and what is required from the user.
• Connection Parameters - Data Schema of input you want the user to enter.
• Help URL - link to a relevant help article where user can learn more about the authentication process.

Authentication Options

You can define multiple authentication options for a connector using the options field. This allows users to choose between different authentication methods:

auth:
  type: client-credentials
  # Common auth settings
  options:
    api-key:
      type: client-credentials
      title: API Key Authentication
      # Option-specific settings
      ui:
        schema:
          type: object
          properties:
            apiKey:
              type: string
              title: API Key
    oauth:
      type: oauth2
      title: OAuth Authentication
      enabled:
        # Only enable oauth2 if clientId is set
        $var: connectorParameters.clientId 
      # Option-specific settings
      getOAuthConfig:
        implementationType: mapping

Connector Parameters

If connector logic can be parametrized by developers using the connector, the schema of these parameters should be defined in the connector spec.

The most common use of connector parameters is providing clientId/clientSecret for OAuth authentication.

Connector parameters will be available in some of the functions used in the connector implementation, mostly in its Authentication implementation.

You can use connector parameters as variables inside Formulas in the connector definition. Specifically, the following parameters support formulas:

• auth.enabled and auth.options.x.enabled to enable or disable auth options based on the connector parameters.