Advanced: Custom Integrations

If you need to create an integration that does not exist in PixieBrix, use these docs. This can be particularly helpful for handling authorization for HTTP requests.

Integrations instruct PixieBrix how to authenticate requests to 3rd-party APIs and services.

When you activate or deploy a mod, you can choose which integration configuration to use. By creating a PixieBrix Team Account, you can share integrations configurations with your team

PixieBrix supports the following authentication methods for user-defined integrations:

• API Key/Shared Secret

• HTTP Basic Auth

• Token

• OAuth2 Implicit Grant

• OAuth2 PKCE

• OAuth2 Client Credentials Grant

To create your own integration, you'll need to go to the Workshop section of the Extension Console and create a new brick.

Example Integration Definition for Giphy

The following is an example integration definition for the Giphy API:

# PixieBrix Runtime Directive 
apiVersion: v3

# Package Metadata
kind: service
metadata:
  id: "@pixies/giphy/giphy-service"
  version: 1.0.0
  name: GIPHY API
  description: Integration for GIPHY API
  url: "https://api.giphy.com/*"

# Origin Allowlist
isAvailable:
    matchPatterns: "https://api.giphy.com/*"

# JSON Schema for configuration options
inputSchema:
  $schema: "https://json-schema.org/draft/2019-09/schema#"
  type: object
  properties:
    token:
      $ref: "https://app.pixiebrix.com/schemas/key#"
      description: "Your GIPHY token, can be found under https://developers.giphy.com/dashboard/?"
  required:
    - token

# Authentication definition, supports Mustache templates
authentication:
  headers:
    Accept: "application/json"
  params:
    api_key: "{{{token}}}"

Integration Definition Schema

Input Schema

The inputSchema section defines a JSON Schema for the configuration options to expose for the integration.

It must be type: object and contain only primitive properties (i.e., string, boolean, number)

inputSchema:
  type: object
  properties:
    requiredOption:
      type: string
    anotherOption:
      type: string
  required:
    - requiredOption

Marking Secrets/Credentials

Secrets (e.g., API keys and tokens) can be marked using $ref: https://app.pixiebrix.com/schemas/key#

Secrets are not made available to bricks. And, by default, secrets from team integrations configurations are not shared with team members.

Here is an example of marking an API key:

inputSchema:
  type: object
  properties:
    apiKey:
      title: API Key
      $ref: https://app.pixiebrix.com/schemas/key#
      description: Your API key
  required:
    - apiKey

Authentication Definition

The authentication section defines how to authenticate requests made to the service, given a configuration.

Mustache Templates

The authentication section can reference any of the properties specified in the inputSchema, including secrets. The authentication section supports the Mustache template language.

By default, Mustache automatically escapes special characters. Use three braces {{{ to disable auto-escaping for an expression.

For example, the @pixiebrix/api has the following authentication definition to configure the Authorization header:

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

authentication.baseURL

The base URL to make requests against. Use 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 HTTP Request Brick) 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/

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.basic

The basic section defines the username and password for HTTP Basic Auth. PixieBrix automatically encodes the secret.

basic:
  username: "{{{username}}}"
  password: "{{{password}}}"

authentication.token

The token section instructs PixieBrix how to exchange a username/password for a token to use for API calls:

token:
    # The URL to request a token
    url: "{{{ controlRoomUrl }}}/v1/authentication"
    # The properties to pass in the POST JSON payload
    data:
      username: "{{{ username }}}"
      password: "{{{ password }}}"
# headers and params can reference properties returned from the token endpoint
headers:
    X-Authorization: "{{{ token }}}"

authentication.oauth2

OAuth2 APIs require the user authenticate with the provider to acquire a Json Web Token (JWT). The token is then used for requests to the APIs.

OAuth2 PKCE

OAuth2 PKCE is the preferred method for authentication of Single-Page Application and Native Clients that cannot securely store a secret key.

To use OAuth2 PKCE, provide the authorization/token URLs, client id, and code challenge method (currently only S256 is supported):

oauth2:
    authorizeUrl: "https://cloud.uipath.com/identity_/connect/authorize"
    tokenUrl: "https://cloud.uipath.com/identity_/connect/token"
    code_challenge_method: S256
    scope: "{{{ scopes }}}"
    client_id: "{{{ appId }}}"

Origin Allowlist: isAvailable

The Origin Allowlist currently does not support Mustache Templates

The isAvailable section defines URL patterns that the integration is allowed to authenticate.

Allowlisting origins prevents authentication credentials from accidentally being sent to another service.

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

See the Chrome Documentation for valid match pattern syntax.

Non-Interactive OAuth2 Token Refresh

If the device's token is expired, PixieBrix first attempts to non-interactively attempt to retrieve a new token.

If the service's authentication flow includes Javascript/front-end redirects instead of server-redirects, provide a nonInteractive section:

nonInteractive:
    # True abort on page load (default). False will wait for Javascript redirect
    abortOnLoad: true
    # Timeout in milliseconds. Only used if abortOnLoad is false
    timeoutMs: 1000

Integration Definition Examples

Dynamic Base URL to support multiple environments

Suppose you have an API served in multiple environments:

• my-api-dev.example.com

• my-api-test.example.com

• my-api-prod.example.com

To support multiple environments with the same mod, expose an integration input property. Then, use the input property to construct the authentication.baseURL directive. PixieBrix makes requests to relative URLs relative to the active integration's baseURL.

# PixieBrix Runtime Directive 
apiVersion: v3

# Package Metadata
kind: service
metadata:
  id: "@pixies/docs/baseurl-example"
  version: 1.0.0
  name: My API
  description: My API that allows varying the base URL

# JSON Schema for configuration options
inputSchema:
  $schema: "https://json-schema.org/draft/2019-09/schema#"
  type: object
  properties:
    origin:
      type: string
      format: uri
      description: The base URL 
      # To show a dropdown, you could use an enum
      # enum:
      #   - https://my-api-dev.example.com
      #   - https://my-api-test.example.com
      #   - https://my-api-prod.example.com
    apiKey:
      $ref: "https://app.pixiebrix.com/schemas/key#"
      description: Your API Key
  required:
    - apiKey
    - origin

# Authentication definition, supports Mustache templates
authentication:
  baseURL: "{{{ origin }}}"
  headers:
    Accept: "application/json"
  params:
    api_key: "{{{ apiKey }}}"

OAuth2 Client Credentials

The following is the definition for the generic OAuth2 Client Credentials configuration used by PixieBrix. See OAuth2 Client Credentials for information on configuring in the Admin Console.

apiVersion: v3
kind: service
metadata:
  id: "@pixies/integrations/oauth2-client-credentials"
  version: 1.0.1
  name: OAuth2 Client Credentials
  description: A generic OAuth2 client credentials integration definition
inputSchema:
  $schema: "https://json-schema.org/draft/2019-09/schema#"
  type: object
  properties:
    clientId:
      title: "Client (application) ID"
      description: The client (application) ID
      type: string
    clientSecret:
      title: "Client Secret"
      description: The client secret
      $ref: "https://app.pixiebrix.com/schemas/key#"
    tokenUrl:
      title: Access Token URL
      type: string
      format: uri
      description: The URL to generate an access token
    scope:
      title: Scope
      description: One or more scopes to request, separated by spaces
      type: string
  required:
    - clientId
    - clientSecret
    - tokenUrl
uiSchema:
  "ui:order":
    - clientId
    - clientSecret
    - tokenUrl
    - scope
    - "*"
authentication:
  oauth2:
    grantType: "client_credentials"
    tokenUrl: "{{{ tokenUrl }}}"
    scope: "{{{ scope }}}"
    client_id: "{{{ clientId }}}"
    client_secret: "{{{ clientSecret }}}"
  headers:
    Authorization: "Bearer {{{ access_token }}}"