​

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 tool
• version: 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:

1. Basic Information

   • name: App name
   • unique_key: Unique identifier for the app
   • description: Brief description of the app
   • logo: URL to the app’s logo
   • categories: List of categories the app belongs to. Examples include:
     • productivity
     • marketing
     • social
     • crm
   • docs: Link to the app’s documentation

2. 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 URL
       • token_url: Token endpoint URL
       • default_scopes: Default OAuth scopes
       • available_scopes: List of all available scopes
       • authorization_params: Additional parameters for authorization (e.g., response_type, user_scopes)
     • For OAuth1:
       • authorization_url: OAuth authorization URL
       • request_url: Request token URL
       • token_url: Access token URL
       • signature_method: Signature method (e.g., HMAC-SHA1)
       • default_scopes: Default OAuth scopes
       • scope_separator: Character used to separate scopes
     • For API Key:

       proxy:
         base_url: "{{base_url}}"
         headers:
           Authorization: "{{api_key}}"
       

     • For Basic Auth: username and password fields are required. You can use them in the proxy/header section directly like:

       proxy:
         headers:
           username: "{{username}}"
           password: "{{password}}"
       

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

4. Custom Fields Custom fields are defined within the auth_schemes section and provide additional configuration options for the integration. They are typically found under the fields key of an auth scheme.

   Common attributes for custom fields include:

   • name: Unique identifier for the field
   • display_name: Human-readable name for the field
   • description: Detailed explanation of the field’s purpose
   • type: Data type of the field (e.g., string, boolean)
   • required: Whether the field is mandatory
   • expected_from_customer: Indicates if the end customer needs to provide this information
   • default: 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"
   

5. Additional Configuration

   • callback_url: URL for OAuth callback
   • token_response_metadata: List of metadata fields expected in the token response
   • proxy: 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 requests
     • headers: Custom headers to be included in the request
     • query_params: Custom query parameters to be included in the request
     • path_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: