Integrations
Allow your users to connect with any Apps.
OpenAPI Specification
Make sure to have info
section in your OpenAPI Specification. In the info section, you should have the following fields:
title
: Name of the toolversion
: Version of the tool/spec
Integration YAML Configuration
This README provides an overview of the integration.yaml
file structure used for configuring app integrations, with a focus on custom fields.
File Structure
The integration.yaml
file typically includes the following key sections:
-
Basic Information
name
: App nameunique_key
: Unique identifier for the appdescription
: Brief description of the applogo
: URL to the app’s logocategories
: List of categories the app belongs to. Examples include:- productivity
- marketing
- social
- crm
docs
: Link to the app’s documentation
-
Authentication Schemes
auth_schemes
: List of authentication methods supported-
name
: Name of the auth scheme -
auth_mode
: Authentication mode (Supported modes: OAUTH2, BASIC, API_KEY, OAUTH1) -
For OAuth2:
authorization_url
: OAuth authorization URLtoken_url
: Token endpoint URLdefault_scopes
: Default OAuth scopesavailable_scopes
: List of all available scopesauthorization_params
: Additional parameters for authorization (e.g.,response_type
,user_scopes
)
-
For OAuth1:
authorization_url
: OAuth authorization URLrequest_url
: Request token URLtoken_url
: Access token URLsignature_method
: Signature method (e.g., HMAC-SHA1)default_scopes
: Default OAuth scopesscope_separator
: Character used to separate scopes
-
For API Key:
-
For Basic Auth:
username
andpassword
fields are required. You can use them in the proxy/header section directly like:proxy: headers: username: "{{username}}" password: "{{password}}"
-
-
Endpoints
get_current_user_endpoint
: Endpoint for retrieving current user info. This is used to check if the auth is valid and refresh the token if it is expired.
-
Custom Fields Custom fields are defined within the
auth_schemes
section and provide additional configuration options for the integration. They are typically found under thefields
key of an auth scheme.Common attributes for custom fields include:
name
: Unique identifier for the fielddisplay_name
: Human-readable name for the fielddescription
: Detailed explanation of the field’s purposetype
: Data type of the field (e.g., string, boolean)required
: Whether the field is mandatoryexpected_from_customer
: Indicates if the end customer needs to provide this informationdefault
: Default value for the field (if applicable)
Examples of custom fields:
a. API Key field:
fields: - name: api_key display_name: API Key description: "Your API key for authentication." type: string required: true expected_from_customer: true
b. Instance URL field (e.g., for Salesforce):
fields: - name: instanceUrl display_name: Instance URL description: "The base URL for your instance, used for API requests." type: string required: true expected_from_customer: true
c. Subdomain field (e.g., for PostHog):
fields: - name: subdomain display_name: Sub Domain description: "Your PostHog subdomain (e.g., 'app' for app.posthog.com)." type: string required: true default: "app"
-
Additional Configuration
callback_url
: URL for OAuth callbacktoken_response_metadata
: List of metadata fields expected in the token responseproxy
: Configuration for API request proxying. This section defines the data to be used in the request. It can use the fields defined via jinja templating{{field_name}}
. It can include:base_url
: The base URL for API requestsheaders
: Custom headers to be included in the requestquery_params
: Custom query parameters to be included in the requestpath_params
: Custom path parameters to be included in the request
Example of a proxy configuration:
proxy: base_url: "https://api.example.com/v1" headers: Authorization: "Bearer {{access_token}}" Content-Type: "application/json" query_params: api_key: "{{api_key}}"
In this example,
{{access_token}}
and{{api_key}}
are placeholders that will be replaced with actual values from the authentication process or custom fields.
Usage of Custom Fields
Custom fields are used to gather necessary information from users or provide default configurations for the integration. They can be referenced in other parts of the configuration using placeholders, typically in the format {{field_name}}
.
For example, in the proxy configuration:
Was this page helpful?