- Input Schema
- Secrets
- Authentication
- authentication.params
- authentication.headers
- authentication.oauth2
- authentication.baseURL
- isAvailable
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/*