🔧 Crafting Custom Tools

Creating custom tools on Composio is straightforward and can be done via an OpenAPI Spec. Here’s a quick video on how you can add a custom integration to Composio using OpenAPI Spec.

Also, feel free to go through the below step by step guide on how to create a custom integration using OpenAPI Spec.

Create or get the OpenAPI Spec for the App

The first step is to get the OpenAPI Spec for the app you want to integrate with Composio. If the app does not have an OpenAPI Spec, you can create one using the Swagger Editor.

Create the integrations.yaml File

Create an integrations.yaml file. Below is the base template for the Integrations.yaml file for any custom tool that you create. However, you will modify the auth schems as each tool supports differnt auth methods.

name:
docs:
description:
logo:
categories: [""]
get_current_user_endpoint: ""

auth_schemes:

// OAuth1 
- scheme_name: 
	auth_mode: OAuth1
	request_url:
	authorization_url: 
token_url:
signature_method:
default_scopes: [""]
scope_separator: ','
authorization_params:
    expiration:
token_params:
    grant_type:
proxy:
  base_url: "{{base_url}}"
fields:
  - name: base_url
    displayName: Base URL
    description: "desc_here"
    type: string
    default: {{add the api endpoint URL of the app}}

// OAuth2 
- scheme_name: 
	auth_mode: OAUTH2
	authorization_url: 
token_url:
default_scopes: [""]
scope_separator: ','
token_access_request_method: 
authorization_params:
    response_type:
token_params:
    grant_type:
proxy:
  base_url: "{{base_url}}"
fields:
  - name: base_url
    displayName: Base URL
    description: "desc_here"
    type: string
    default: {{api endpoint URL of the app}}
    
    
// API-KEY
- scheme_name: app_name_api-key
  auth_mode: API_KEY
  proxy:
  base_url: "{{base_url}}"
  headers:
    Authorization: "{{api_key}}"
fields:
  - name: api_key
    expected_from_customer: true 
    displayName: API Key
    description: "add_desc_here"
    type: string
    required: true
  - name: base_url
    expected_from_customer: true 
    displayName: Base URL
    description: "add_desc_here"
    type: string
    required: false
    default: {{add the api endpoint URL of the app}}

    
// BASIC
- scheme_name: app_name_basic
auth_mode: BASIC
proxy:
  base_url: {{add the api_endpoint_url}}
fields:
  - name: api_key
    displayName: API Key
    description: "desc_here"
    type: string
    expected_from_customer: true
  - name: username
    displayName: Username
    description: "desc_here"
    type: string
    expected_from_customer: 
  - name: password
    displayName: Password
    description: "your password here."
    type: string
    expected_from_customer: true

Let’s start with creating the yaml file for GitHub by adding the basic info.

name: GitHub
description: Integrate GitHub to manage your repositories directly from Composio.
logo: https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png
categories: ["developer tools", "version control"]
auth_schemes:

Determine the supported auth method by the custom tool that you’re trying to add. Each Auth Method has its own set of fields. These fields are defined under the Auth Method. Please remember that the integrations.yaml file is indentation sensitive and should be formatted correctly.

You can refer to below snippets of the each auth method to see how these fields are defined. You can add the supported auth methods in the integrations.yaml file by copying from the below snippets.

  - scheme_name: tool_name_oauth1
    auth_mode: OAUTH1
    request_url:
    authorization_url: 
    
    token_url:
    signature_method:
    default_scopes: [""]
    scope_separator: ','
    authorization_params:
        expiration:
    token_params:
        grant_type:
    proxy:
      base_url: "{{base_url}}"
    fields:
      - name: base_url
        displayName: Base URL
        description: "desc_here"
        type: string
        default: {{add the api endpoint URL of the app}}

  - scheme_name: tool_name_oauth2
    auth_mode: OAUTH2
    authorization_url: 
    token_url:
    default_scopes: [""]
    scope_separator: ','
    token_access_request_method: 
    authorization_params:
        response_type:
    token_params:
        grant_type:
    proxy:
      base_url: "{{base_url}}"
    fields:
      - name: base_url
        displayName: Base URL
        description: "desc_here"
        type: string
        default: {{api endpoint URL of the app}}

  - scheme_name: app_name_api_key
    auth_mode: API_KEY
    proxy:
      base_url: "{{base_url}}"
      headers:
        Authorization: "{{api_key}}"
    fields:
      - name: api_key
        expected_from_customer: true 
        displayName: API Key
        description: "add_desc_here"
        type: string
        required: true
      - name: base_url
        expected_from_customer: true 
        displayName: Base URL
        description: "add_desc_here"
        type: string
        required: false
        default: {{add the api endpoint URL of the app}}

  - scheme_name: app_name_basic
    auth_mode: BASIC
    proxy:
      base_url: {{add the api_endpoint_url}}
    fields:
      - name: api_key
        displayName: API Key
        description: "desc_here"
        type: string
        expected_from_customer: true
      - name: username
        displayName: Username
        description: "desc_here"
        type: string
        expected_from_customer: 
      - name: password
        displayName: Password
        description: "your password here."
        type: string
        expected_from_customer: true

Most tools have their auth methods listed in their docs. You can usually find it by searching “custom_tool_name auth docs” on Google. The first result often has what you need.

In this case, GitHub uses OAuth2 for authentication.

name: GitHub
description: Integrate GitHub to manage your repositories directly from Composio.
logo: https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png
categories: ["developer tools", "version control"]

auth_schemes:
  - scheme_name: github_oauth2
    auth_mode: OAUTH2
    authorization_url: "https://github.com/login/oauth/authorize"
    token_url: "https://github.com/login/oauth/access_token"
    default_scopes: ["repo", "admin:org"]
    token_params:
      grant_type: authorization_code
    authorization_params:
      response_type: code
    proxy:
      base_url: "{{base_url}}"
    fields:
      - name: base_url
        displayName: Base URL
        description: "The API base URL for GitHub"
        type: string
        default: https://api.github.com

You need to add the relevant scopes as needed. Now that you have the integrations.yaml file ready, push the code and copy the URL of the repository.

Add your Custom Tool on Composio

Go to the settings page on Composio, Go to Add Open API spec section and upload the Open API Spec file and the integrations.yaml file. Click on the “Start import” button to test.

Testing Your Custom tool on Composio

Navigate back to the tools catalogue page on Composio. Search for the tool you just created, click on it, and proceed to connect your account.

If you face any issues or found any bugs, join our Discord to chat with the team or write to us at tech@composio.dev.

You can also add the actions to your custom tools. Click on the next article to read on how to create actions for your custom tool.

Introduction

Python

Javascript

SweKit

SweKit.js

CLI

🔧 Crafting Custom Tools