Docs
Start typing to search…

Connectors

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

Example connector definition:

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

type: client-credentials

# User input configuration
inputSchema:
  type: object
  # Description shown to users when creating a connection (supports markdown)
  description: "If you are not sure where to get the information below, follow [this link](https://docs.example.com/api-authentication)."
  properties:
    apiKey:
      type: string
      title: "API Key"

# Connector functions (see below)
# These reference files in your connector directory
makeApiClient:
  type: mapping
  mapping:
    baseUri: https://api.example.com
    headers:
      Authorization:
        $concat:
          - "Bearer "
          - $var: credentials.api_token

test:
  type: javascript
  code: |
    export default async function ({ externalApiClient }) {
      const responseData = await externalApiClient.get("/current-user")
      return responseData.email !== undefined
    }

# ... properties and functions based on the connector type

Connector definition has the following properties:

  • name: Display name of the connector.
  • key: Unique identifier for the connector.
  • appUuid: UUID of an External App.
  • logoUri: URL to the connector's logo (should be publicly available)
  • type: one of the Connector Types.
  • parametersSchema: Data Schema for connector parameters (see below)
  • inputSchema: Data Schema defining what inputs to request from users when creating a connection. The description field can contain markdown and is displayed to users to help them understand where to find the required credentials.
  • List of Connector Functions.
  • options: different options for authentication and accessing the external app if supported by the external API.

Connector Functions

Connector has a number of Membrane Functions implementing its logic. The composition of these functions is determined by the connector type.

User Input

You can configure what inputs to request from users when they create a connection, and provide helpful guidance on where to find the required credentials.

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

The inputSchema is a Data Schema with these key properties:

  • properties - defines the fields users need to fill in (e.g., API key, subdomain). These values will be copied to the connection parameters and will become connection credentials by default (unless you override this behavior).
  • description - help text shown to users explaining where to find the required credentials. Supports markdown, so you can include links to documentation.

Custom Credentials Schema

By default, credentials schema for the connector is auto-calculated based on other parameters (type, inputSchema, etc). However, when you use getCredentialsFromConnectionParameters to transform user input into a different credential structure, you should define customCredentialsSchema to describe the actual shape of your credentials.

This is useful when:

  • Your credentials have a different structure than the user input (e.g., generating tokens from API keys)
  • You need to fetch additional data during connection setup (e.g., user ID, organization info)
  • You want to store computed values alongside the original input

Example:

# Connector definition: Custom credentials with transformed structure

type: client-credentials

inputSchema:
  type: object
  description: "Enter your API key from the [Settings page](https://example.com/settings)."
  properties:
    apiKey:
      type: string
      title: 'API Key'

# Define the actual structure of credentials after transformation
customCredentialsSchema:
  type: object
  properties:
    apiKey:
      type: string
    userId:
      type: string
    organizationId:
      type: string

# Transform user input into credentials
getCredentialsFromConnectionParameters:
  type: javascript
  code: |
    export default async function ({ connectionInput }) {
      // Fetch additional info using the API key
      const response = await fetch("https://api.example.com/me", {
        headers: { "Authorization": `Bearer ${connectionInput.apiKey}` }
      })
      const userInfo = await response.json()

      return {
        apiKey: connectionInput.apiKey,
        userId: userInfo.id,
        organizationId: userInfo.organizationId
      }
    }

When customCredentialsSchema is defined, it describes the structure that getCredentialsFromConnectionParameters returns and what will be stored as the connection credentials.

Connector Options

You can define multiple options for a connector using the options field. This allows users to choose between different authentication methods or other parameters related to accessing the external app.

Each option has:

  • title - display name for the option
  • description - description of the option
  • enabled - formula to conditionally enable/disable the option (for example, you may want to enable oauth option only if clientId is provided in the connector parameters)
  • Any connector function or property related to the connector type.

All options will inherit functions and properties from the connector definition if not overriden on the option level.

If options are defined, the connector itself should not have a type property.

Example connector definition with options:

# API client definition will be shared across all optoins
makeApiClient:
  type: mapping
  mapping:
    baseUri: https://api.example.com
    headers:
      Authorization:
        $concat:
          - 'Bearer '
          - $var: credentials.api_token

options:
  api-token:
    title: API Token
    description: Provide your personal API token to connect
    type: client-credentials
    inputSchema:
      type: object
      description: "Find your API token in [Account Settings](https://example.com/settings/api)."
      properties:
        apiToken:
          type: string
          title: 'API Token'
  oauth:
    title: OAuth
    description: Authorize this app to access your account via UI flow.
    type: oauth2
    getOAuthConfig:
      type: mapping
      mapping:
        clientId:
          $var: connectorParameters.clientId
        clientSecret:
          $var: connectorParameters.clientSecret
        authorizeUri: https://api.example.com/oauth/authorize
        tokenUri: https://api.example.com/oauth/token

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 functions related to authentication.

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

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

Updated 2 days ago