šŸ“–
PixieBrix Documentation
šŸŒ¤ļø

Defining Integrations

Integrations are re-usable resources and configuration that can also be used to authenticate requests to APIs. By creating a PixieBrix account, you can share service configurations with your team

Examples of when to use integrations:

  • An API credential
  • An API with OAuth2 authentication for each user, e.g., Salesforce
  • A shared Google Sheet

Input Schema

The inputSchema section defines the configuration options to expose for the service. It must be a type: object, containing only primitive properties (i.e., string, boolean, number)

inputSchema:
  type: object
  properties:
   configOption:
     type: string
   anotherOption:
     type: string

Secrets

Secrets (e.g., API keys) can be marked usingĀ $ref: https://app.pixiebrix.com/schemas/key#. Secrets can only be referenced in theĀ authenticationĀ section.

Secrets are not made available to bricks. Additionally, secrets configured for team service configurations are not shared with team members. Configured team services with secrets are proxied through PixieBrix to authenticate the request

inputSchema:
  type: object
  properties:
    apiKey:
      $ref: https://app.pixiebrix.com/schemas/key#
  required:
    - apiKey

Authentication

The authentication section defines how to authenticate requests made to the service, given the configuration. The authentication section can reference any of the properties specified in the inputSchema, including secrets.

For example, the @pixiebrix/api has the following authentication definition:

inputSchema:
  type: object
  properties:
    apiKey:
      $ref: https://app.pixiebrix.com/schemas/key#
  required:
    - apiKey
authentication:
  headers:
    Authorization: Token {{apiKey}}

authentication.params

HTTP parameters to include in the request. The arguments are automatically URL encoded

params:
  key: apiKey

authentication.headers

HTTP headers to include in the request. Example from our Rapid API service definition:

headers:
  # key is a secret in the configuration
  x-rapidapi-key: "{{key}}"
  x-rapidapi-host: "{{host}}"
  useQueryString: "true"

authentication.oauth2

OAuth2 APIs require the user authenticate with the provider. To configure the authentication flow, add an additional oauth2 entry to the authentication section:

oauth2:
  # the host for the oauth2 authentication flow, e.g., 
  # https://login.salesforce.com/
  host: "{{&host}}"# the application key for your oauth2 provider
  client_id: "{{consumerKey}}"

authentication.baseURL

The base URL to make requests against. Used for services where the URL host or path varies by account.

If a baseURL is configured, relative URLs in requests (e.g., made by theĀ @pixiebrix/get) using the service will use the configured baseURL. The constructed absolute URL is validated against theĀ isAvailableĀ configuration (see below)

baseURL: https://{{ domain }}.service.com/

isAvailable

The isAvailable section defines which URL patterns the service is allowed to authenticate. This prevents authentication credentials from accidentally being sent to another service.

See the Common Configuration Sections page for more details on isAvailable and matchPatterns entries

isAvailable:
  matchPatterns: https://*.salesforce.com/*
Twitter