Toolkits
Toolkits are collections of related tools grouped by service or functionality. For example, the GitHub toolkit contains all GitHub-related tools like creating repositories, managing issues, and handling pull requests.
Overview
The Toolkits class manages toolkit operations in the Composio SDK. Toolkits serve as a replacement for the “apps” concept in the Composio API, providing a more organized way to access tools.
Source: ts/packages/core/src/models/Toolkits.ts
Retrieve detailed information about a single toolkit:
// Get a specific toolkit by slug
const githubToolkit = await composio.toolkits.get('github');
console.log(githubToolkit.name); // GitHub
console.log(githubToolkit.authConfigDetails); // Authentication configuration details
// Get all toolkits
const allToolkits = await composio.toolkits.get({});
// Get toolkits by category
const devToolkits = await composio.toolkits.get({
category: 'developer-tools'
});
// Get local toolkits
const localToolkits = await composio.toolkits.get({
isLocal: true
});
// Get toolkits with pagination
const toolkits = await composio.toolkits.get({
limit: 20,
cursor: 'next_page_cursor'
});
// Get all toolkit categories
const categories = await composio.toolkits.listCategories();
console.log(categories.items); // Array of category objects
- Communication (Slack, Discord, Email)
- Developer Tools (GitHub, GitLab, Jira)
- Productivity (Google Calendar, Notion, Trello)
- CRM (Salesforce, HubSpot)
- And many more
Authentication Fields
Get Auth Config Creation Fields
Retrieve the fields required to create an auth config for a toolkit:
import { AuthSchemeTypes } from '@composio/core';
// Get all required and optional fields
const fields = await composio.toolkits.getAuthConfigCreationFields(
'github',
AuthSchemeTypes.OAUTH2
);
// Get only required fields
const requiredFields = await composio.toolkits.getAuthConfigCreationFields(
'github',
AuthSchemeTypes.OAUTH2,
{ requiredOnly: true }
);
console.log(requiredFields);
// Example output:
// [
// {
// name: 'client_id',
// type: 'string',
// description: 'OAuth client ID',
// required: true
// },
// {
// name: 'client_secret',
// type: 'string',
// description: 'OAuth client secret',
// required: true
// }
// ]
Get Connected Account Initiation Fields
Retrieve the fields required to initiate a connected account:
import { AuthSchemeTypes } from '@composio/core';
// Get all fields for connected account initiation
const fields = await composio.toolkits.getConnectedAccountInitiationFields(
'github',
AuthSchemeTypes.OAUTH2
);
// Get only required fields
const requiredFields = await composio.toolkits.getConnectedAccountInitiationFields(
'github',
AuthSchemeTypes.OAUTH2,
{ requiredOnly: true }
);
If a toolkit has multiple authentication schemes, you should specify the authScheme parameter. If not specified, the SDK will use the first available authentication scheme and log a warning.
authorize method provides a convenient way to connect a user to a toolkit:
// Authorize a user to use a toolkit
const connectionRequest = await composio.toolkits.authorize('user_123', 'github');
// With a specific auth config
const connectionRequest = await composio.toolkits.authorize(
'user_123',
'github',
'auth_config_abc'
);
How Authorization Works
- Checks if an auth config exists for the toolkit
- If not found and an
authConfigId is provided, uses that
- If no auth config exists, creates one using Composio-managed authentication
- Creates a connection request for the user
- Returns a
ConnectionRequest object
The authorize method automatically allows multiple connected accounts per user for an auth config. If you need different behavior, use the connectedAccounts.initiate() method directly.
Example: Complete Authorization Flow
// Authorize and wait for connection
const connectionRequest = await composio.toolkits.authorize('user_123', 'github');
if (connectionRequest.redirectUrl) {
console.log(`Visit: ${connectionRequest.redirectUrl}`);
// Wait for the user to complete authentication
const connectedAccount = await connectionRequest.waitForConnection();
console.log(`Connected: ${connectedAccount.id}`);
}
slug - Unique identifier (e.g., ‘github’)name - Human-readable name (e.g., ‘GitHub’)description - Toolkit descriptionlogo - Toolkit logo URLcategories - Array of categories the toolkit belongs toauthConfigDetails - Available authentication schemes and their requirementsisLocal - Whether the toolkit runs locallyisDeprecated - Whether the toolkit is deprecateddocumentation - Link to toolkit documentation
Authentication Config Details
The authConfigDetails property contains information about available authentication methods:
const toolkit = await composio.toolkits.get('github');
toolkit.authConfigDetails.forEach(authConfig => {
console.log(authConfig.mode); // e.g., 'OAUTH2', 'API_KEY', 'BASIC'
console.log(authConfig.fields.authConfigCreation.required); // Required fields
console.log(authConfig.fields.authConfigCreation.optional); // Optional fields
console.log(authConfig.fields.connectedAccountInitiation.required); // Required for connection
});
Advanced Filtering
Combine multiple filters to find specific toolkits:
// Get toolkits managed by a specific provider
const toolkits = await composio.toolkits.get({
managedBy: 'composio'
});
// Sort toolkits
const sortedToolkits = await composio.toolkits.get({
sortBy: 'name', // or 'created_at', 'updated_at'
limit: 50
});
Error Handling
Common errors when working with toolkits:
ComposioToolkitNotFoundError - Toolkit with the given slug doesn’t existComposioToolkitFetchError - Error fetching toolkits from the APIComposioAuthConfigNotFoundError - No auth config found for the toolkitValidationError - Invalid parameters passed to toolkit methods
Example Error Handling
import { ComposioToolkitNotFoundError } from '@composio/core';
try {
const toolkit = await composio.toolkits.get('nonexistent-toolkit');
} catch (error) {
if (error instanceof ComposioToolkitNotFoundError) {
console.error('Toolkit not found:', error.message);
console.log('Available toolkits can be listed with toolkits.get({})');
} else {
throw error;
}
}
Use Cases
// Get GitHub toolkit and list its tools
const githubToolkit = await composio.toolkits.get('github');
const githubTools = await composio.tools.getRawComposioTools({
toolkits: ['github']
});
console.log(`${githubToolkit.name} has ${githubTools.length} tools`);
Check Authentication Requirements
// Check what authentication is needed for a toolkit
const toolkit = await composio.toolkits.get('slack');
if (toolkit.authConfigDetails && toolkit.authConfigDetails.length > 0) {
console.log('Authentication schemes available:');
toolkit.authConfigDetails.forEach(auth => {
console.log(`- ${auth.mode}`);
});
} else {
console.log('No authentication required');
}
// Get all categories and their toolkits
const categories = await composio.toolkits.listCategories();
for (const category of categories.items) {
const toolkits = await composio.toolkits.get({
category: category.slug
});
console.log(`${category.name}: ${toolkits.items.length} toolkits`);
}