Comment on page
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
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.
Example: allowlisting calls to Salesforce APIs
Zapier
Storing Data with Team Databases
Last modified 8d ago