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.

# 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}}}"
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
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
The
authentication
section defines how to authenticate requests made to the service, given a configuration.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}}}"
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/
HTTP parameters to include in the request. The arguments are automatically URL encoded
params:
key: "{{{ apiKey }}}"
headers:
# key is a secret in the configuration
x-rapidapi-key: "{{key}}"
x-rapidapi-host: "{{host}}"
useQueryString: "true"
The basic section defines the username and password for HTTP Basic Auth. PixieBrix automatically encodes the secret.
basic:
username: "{{{username}}}"
password: "{{{password}}}"
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 }}}"
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 }}}"
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
entriesLast modified 8d ago