Connected Account Initiate Now Filters by ACTIVE Status

Version Information

TypeScript/JavaScript

• Package: @composio/core
• Version: 0.5.4+

Python

• Package: composio
• Version: 0.10.9+

The initiate() method now only considers ACTIVE connected accounts when checking for duplicates. Previously, expired or inactive accounts would incorrectly trigger the multiple accounts error.

What Changed

When calling connectedAccounts.initiate(), the SDK now filters by statuses: ["ACTIVE"] when checking for existing accounts. This prevents expired or inactive accounts from blocking new connection creation.

Before (Bug)

1
// Expired accounts would incorrectly trigger ComposioMultipleConnectedAccountsError
2
await composio.connectedAccounts.initiate(userId, authConfigId);
3
// ❌ Error: Multiple connected accounts found (even if they're all expired)

After (Fixed)

1
// Only ACTIVE accounts are considered
2
await composio.connectedAccounts.initiate(userId, authConfigId);
3
// ✅ Works - expired/inactive accounts are ignored

Affected SDKs

• TypeScript: @composio/core
• Python: composio

Backward Compatibility

This is a bug fix with no breaking changes. The behavior now matches the expected intent of the multiple accounts check.

[Critical] File Upload/Download Fixes for latest tool with anyOf, oneOf, and allOf Schemas

Version Information

TypeScript/JavaScript

• Package: @composio/core and provider packages
• Version: 0.5.3+

Python

• Package: composio and provider packages
• Version: 0.10.8+

The file handling modifiers now properly handle file_uploadable and file_downloadable properties nested within anyOf, oneOf, and allOf JSON Schema declarations. Previously, only direct child properties (and partial allOf support) were detected for file upload/download transformations.

What Changed

Before (Bug)

File properties inside anyOf, oneOf, or allOf were not detected:

1
// This schema's file_uploadable was NOT being processed
2
inputParameters: {
3
  type: 'object',
4
  properties: {
5
    fileInput: {
6
      anyOf: [
7
        {
8
          type: 'string',
9
          file_uploadable: true  // ❌ Not detected
10
        },
11
        {
12
          type: 'null'
13
        }
14
      ]
15
    }
16
  }
17
}

After (Fixed)

File properties are now correctly detected and processed at any nesting level:

1
// Now properly detected and transformed
2
inputParameters: {
3
  type: 'object',
4
  properties: {
5
    fileInput: {
6
      anyOf: [
7
        {
8
          type: 'string',
9
          file_uploadable: true  // ✅ Detected and processed
10
        },
11
        {
12
          type: 'null'
13
        }
14
      ]
15
    }
16
  }
17
}

Affected Scenarios

How to Update

TypeScript/JavaScript

$
npm update @composio/core@latest

Python

$
pip install --upgrade composio

Backward Compatibility

This release is fully backward compatible:

• All existing code continues to work without modifications
• No migration required
• File upload/download for direct properties continues to work as before
• The fix only adds support for previously unsupported schema patterns

Impact Summary

File handling in tool execution now uses presigned URLs

Summary

Files involved in tool execution are now shared via presigned URLs with a default TTL (time-to-live) of 1 hour. You can customize the file TTL through your project configuration.

What changed

When tools return files (images, documents, exports, etc.), these files are now delivered as presigned URLs with a configurable TTL instead of non-expiring URLs. This provides:

• Automatic cleanup - Files expire after the configured TTL
• Configurable retention - Adjust file availability based on your application’s needs

Default behavior

All files returned from tool execution now have a 1 hour TTL by default. After this period, the presigned URLs expire and files are no longer accessible.

Configuring file TTL

You can adjust the file TTL to match your application’s needs.

Via Dashboard

1. Navigate to Project Settings in your Composio dashboard
2. Find the File TTL configuration option
3. Set your desired TTL value

Via API

Use the Update Project Config API to programmatically configure the file TTL:

$
curl -X PATCH "https://backend.composio.dev/api/v3/org/projects/config" \
>
  -H "x-api-key: YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "fileTtl": 3600
>
  }'

Impact

Migration

No code changes are required. Your existing integrations will continue to receive file URLs as before, but these URLs will now expire after the configured TTL.

If your application stores or caches file URLs for later use, ensure you handle URL expiration appropriately by either:

• Downloading files before the TTL expires
• Re-executing the tool to obtain fresh URLs when needed
• Increasing the TTL via project settings to match your retention requirements

True PATCH Semantics for Auth Config Updates

Version Information

TypeScript/JavaScript

• Package: @composio/core and provider packages
• Version: 0.5.1+

Python

• Package: composio-core and provider packages
• Version: 0.10.7+

The PATCH /api/v3/auth_configs/{id} endpoint now implements proper partial update semantics. Previously, omitting fields would clear them (behaving like PUT). Now, omitted fields are preserved—only explicitly provided fields are modified.

What Changed

New Capabilities

Rotate a Single Credential Field

Update just client_secret without resending client_id or other fields:

1
from composio import Composio
2
3
composio = Composio()
4
5
# Only send the field you want to update - other credentials are preserved
6
7
composio.auth_configs.update(
8
"ac_yourAuthConfigId",
9
options={
10
"type": "custom",
11
"credentials": {
12
"client_secret": "new_rotated_secret",
13
},
14
},
15
)

Update Tool Restrictions Without Touching Credentials

Previously, this would fail because credentials was required. Now it works:

1
from composio import Composio
2
3
composio = Composio()
4
5
# Update tool restrictions - credentials are automatically preserved
6
7
composio.auth_configs.update(
8
"ac_yourAuthConfigId",
9
options={
10
"type": "custom",
11
"tool_access_config": {
12
"tools_available_for_execution": ["GMAIL_SEND_EMAIL", "GMAIL_READ_EMAIL"],
13
},
14
},
15
)

Migration Guide

Am I Affected?

Yes, if your code relied on omitting fields to clear them.

No, if you always send complete payloads or only use PATCH to update specific fields.

How to Clear Fields Explicitly

1
from composio import Composio
2
3
composio = Composio()
4
5
# Explicitly clear tool restrictions with empty array
6
7
composio.auth_configs.update(
8
"ac_yourAuthConfigId",
9
options={
10
"type": "custom",
11
"tool_access_config": {
12
"tools_available_for_execution": [],
13
},
14
},
15
)

Raw HTTP API

For users calling the API directly:

$
# Rotate single credential
>
curl -X PATCH "https://backend.composio.dev/api/v3/auth_configs/{id}" \
>
  -H "x-api-key: YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"type": "custom", "credentials": {"client_secret": "new_secret"}}'
>
>
# Clear tool restrictions
>
curl -X PATCH "https://backend.composio.dev/api/v3/auth_configs/{id}" \
>
  -H "x-api-key: YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"type": "custom", "tool_access_config": {"tools_available_for_execution": []}}'

Tool Router Improvements and New Features

Version Information

TypeScript/JavaScript

• Package: @composio/core and provider packages
• Version: 0.3.4 to 0.4.0

Python

• Package: composio-core and provider packages
• Version: 0.10.4 to 0.10.5

New Features

1. Wait for Connections Property

Added waitForConnections (TypeScript) / wait_for_connections (Python) property to manage connections configuration. This allows tool router sessions to wait for users to complete authentication before proceeding to the next step.

TypeScript:

1
const session = await composio.toolRouter.create(userId, {
2
  manageConnections: {
3
    enable: true,
4
    callbackUrl: 'https://example.com/callback',
5
    waitForConnections: true  // NEW
6
  }
7
});

Python:

1
session = tool_router.create(
2
    user_id="user_123",
3
    manage_connections={
4
        "enable": True,
5
        "callback_url": "https://example.com/callback",
6
        "wait_for_connections": True  # NEW
7
    }
8
)

2. Session-Specific Modifier Types

Introduced new modifier types for better session-based tool execution: SessionExecuteMetaModifiers and SessionMetaToolOptions.

TypeScript:

1
const tools = await session.tools({
2
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => schema,
3
  beforeExecute: ({ toolSlug, toolkitSlug, sessionId, params }) => params,
4
  afterExecute: ({ toolSlug, toolkitSlug, sessionId, result }) => result
5
});

Python:

1
from composio.core.models import before_execute_meta, after_execute_meta
2
3
@before_execute_meta
4
def before_modifier(tool, toolkit, session_id, params):
5
    return params
6
7
@after_execute_meta  
8
def after_modifier(tool, toolkit, session_id, response):
9
    return response
10
11
tools = session.tools(modifiers=[before_modifier, after_modifier])

3. Dedicated Method for Tool Router Meta Tools

Added getRawToolRouterMetaTools (TypeScript) / get_raw_tool_router_meta_tools (Python) method in the Tools class for fetching meta tools directly from a tool router session.

TypeScript:

1
const metaTools = await composio.tools.getRawToolRouterMetaTools('session_123', {
2
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
3
    // Customize schema
4
    return schema;
5
  }
6
});

Python:

1
meta_tools = tools_model.get_raw_tool_router_meta_tools(
2
    session_id="session_123",
3
    modifiers=[schema_modifier]
4
)

Internal Improvements

1. Performance Optimization

Eliminated unnecessary tool fetching during tool router execution, resulting in faster tool execution with fewer API calls.

2. Improved Architecture

Tool router sessions now fetch tools directly from the session API endpoint instead of using tool slugs, providing better consistency and reliability.

3. Simplified Implementation

Removed redundant tool schema fetching in execution paths, using a hardcoded ‘composio’ toolkit slug for meta tools.

Backward Compatibility

This release is fully backward compatible:

• All existing code continues to work without modifications
• New properties are optional with sensible defaults
• New modifier types can be adopted incrementally
• Internal changes have no impact on public APIs
• No migration required

Impact Summary

All changes follow semantic versioning principles and maintain full backward compatibility.

Tool Enum Name Shortening

Shortened tool enum names across 181 actions to ensure compatibility with all AI agent frameworks.

Why This Change?

Some agent frameworks have a 64-character limit on tool/function names. Several tool enums exceeded this limit, causing compatibility issues.

No Action Required

This change will not break your integration if you are using latest toolkit versions or fetching tools dynamically. The SDK automatically resolves the correct tool names.

Migration

If you’re referencing any affected tool enums by their old names, update to the new shortened names.

Optional API Key Enforcement for MCP Servers

We’ve introduced a new project-level security setting that allows you to require API key authentication for all MCP server requests. This opt-in feature gives you fine-grained control over who can access your MCP endpoints.

What’s New

A new “Require API Key for MCP” toggle is now available in your Project Settings. When enabled, all requests to your MCP servers must include a valid Composio API key in the request headers.

How It Works

When the setting is disabled (default):

• MCP servers work without API key authentication
• Existing integrations continue to function unchanged

When the setting is enabled:

• All MCP requests must include the x-api-key header with a valid Composio API key
• Requests without a valid API key receive 401 Unauthorized
• Only API keys belonging to the same project are accepted

Request Examples

Without API key (when enforcement is enabled):

$
curl -X POST "https://mcp.composio.dev/{your_mcp_server_url}" \
>
  -H "Content-Type: application/json" \
>
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
>
>
# Response: 401 Unauthorized

With API key:

$
curl -X POST "https://mcp.composio.dev/{your_mcp_server_url}" \
>
  -H "Content-Type: application/json" \
>
  -H "x-api-key: ak_your_api_key" \
>
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
>
>
# Response: 200 OK

Enabling the Setting

Via Dashboard

1. Navigate to Project Settings
2. Go to the Project Configuration tab
3. Find the “Require API Key for MCP” toggle
4. Enable the toggle

Via API

Update your project configuration using the API:

$
curl -X PATCH "https://backend.composio.dev/api/v3/org/project/config" \
>
  -H "Content-Type: application/json" \
>
  -H "x-api-key: ak_your_api_key" \
>
  -d '{"require_mcp_api_key": true}'

Response:

1
{
2
  "require_mcp_api_key": true,
3
  "is_2FA_enabled": true,
4
  "mask_secret_keys_in_connected_account": true,
5
  "log_visibility_setting": "show_all"
6
}

Via Code

1
import requests
2
3
response = requests.patch(
4
    "https://backend.composio.dev/api/v3/org/project/config",
5
    headers={
6
        "Content-Type": "application/json",
7
        "x-api-key": "ak_your_api_key"
8
    },
9
    json={"require_mcp_api_key": True}
10
)
11
12
print(response.json())

When to Use This

Enable API key enforcement when you need to:

• Prevent unauthorized access to your MCP servers
• Control which applications can interact with your MCP endpoints
• Add an extra security layer for production deployments
• Audit and track MCP server usage through API key attribution

API Reference

Get Current Setting

1
GET /api/v3/org/project/config

Update Setting

1
PATCH /api/v3/org/project/config

1
{
2
  "require_mcp_api_key": true
3
}

Consistent Error Response Structure

Tool execution errors now return a standardized response format across all failure types. Previously, the data field was empty on errors—now it always includes status_code and message, matching the structure of successful responses.

What Changed

All error responses from tool execution now include:

• data.status_code: HTTP status code (or null for non-HTTP errors)
• data.message: Detailed error message
• error: Same detailed message at the top level

Before vs After

Previous error response:

1
{
2
  "data": {},
3
  "successfull": false,
4
  "error": "404 Client Error: Not Found for url: ...",
5
}

New error response:

1
{
2
  "data": {
3
      "http_error": "404 Client Error: Not Found for url: ...",
4
      "status_code": 404,
5
      "message": "Resource not found: The requested item does not exist"
6
  },
7
  "successfull": false,
8
  "error": "Resource not found: The requested item does not exist",
9
}

Why This Matters

• Easier parsing: Agents and code can reliably access error details from data.message without special-casing empty data objects
• Better debugging: Detailed error messages replace generic HTTP error strings
• Consistent schema: Same response shape whether the tool succeeds or fails

Union Types Preserved in Tool Schemas

Tool schemas now use standard JSON Schema anyOf for union types, providing accurate type information for LLMs and code generators.

What Changed

Two changes affect how types appear in request/response schemas:

Before vs After

For example, the GOOGLECALENDAR_GET_CURRENT_DATE_TIME request schema changes: Previous (only a single type):

1
{
2
  "timezone": {
3
    "default": 0,
4
    "description": "Timezone specification...",
5
    "title": "Timezone",
6
    "type": "string"
7
  }
8
}

Now (Union types preserved):

1
{
2
  "timezone": {
3
    "anyOf": [
4
      { "type": "string" },
5
      { "type": "number" }
6
    ],
7
    "default": 0,
8
    "description": "Timezone specification...",
9
    "title": "Timezone"
10
  }
11
}

Similarly, nullable fields like page_token in GOOGLECALENDAR_LIST_CALENDARS:

Previous:

1
{
2
  "page_token": {
3
    "default": null,
4
    "description": "Token for the page of results to return...",
5
    "nullable": true,
6
    "title": "Page Token",
7
    "type": "string"
8
  }
9
}

Now:

1
{
2
  "page_token": {
3
    "anyOf": [
4
      { "type": "string" },
5
      { "type": "null" }
6
    ],
7
    "default": null,
8
    "description": "Token for the page of results to return...",
9
    "title": "Page Token"
10
  }
11
}

Why This Matters

• Accurate schemas: LLMs and code generators see the full set of allowed types
• Better validation: Input validation can now correctly accept all valid types, not just the first one

Deprecating BEARER_TOKEN auth scheme for 19 toolkits

We’ve deprecated the BEARER_TOKEN auth scheme for the following 19 toolkits:

• Airtable
• Discord
• Discordbot
• Gmail
• Google Classroom
• Google Search Console
• Google Calendar
• Google Docs
• Google Drive
• Google Slides
• Google Super
• Instagram
• Ntfy
• Sapling AI
• Slack
• Slackbot
• Tawk To
• TikTok
• Twitter

Recommendation

For these toolkits, we recommend using alternative auth schemes (for example, OAUTH2, API_KEY, or other toolkit-supported schemes) instead of BEARER_TOKEN.

Backward compatibility (explicit)

This change is fully backward compatible:

• Existing auth configs and connected accounts created with BEARER_TOKEN will continue to function.
• Creating new auth configs and connected accounts with BEARER_TOKEN will continue to work (e.g., via API/SDK).
• To discourage new usage, BEARER_TOKEN auth configs / connected accounts will not be displayed in the UI for these toolkits.

Binary Data Support for Proxy Execute

The /api/v3/tools/execute/proxy endpoint now supports binary data for both file uploads and downloads.

File Uploads (binary_body)

To upload a file via the proxy, use the binary_body field in your request payload. This supports two approaches: specifying either a URL pointing to the file or providing the base64-encoded content directly.

Upload File via URL

$
curl --location 'https://backend.composio.dev/api/v3/tools/execute/proxy' \
>
  --header 'accept: application/json' \
>
  --header 'x-api-key: <YOUR_API_KEY>' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
    "endpoint": "/upload-endpoint",
>
    "method": "POST",
>
    "connected_account_id": "<CONNECTED_ACCOUNT_ID>",
>
    "binary_body": {
>
      "url": "{URL_TO_THE_FILE}"
>
    }
>
  }'

Upload File via Base64 Content

Supported up to 4MB file size.

$
curl --location 'https://backend.composio.dev/api/v3/tools/execute/proxy' \
>
  --header 'accept: application/json' \
>
  --header 'x-api-key: <YOUR_API_KEY>' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
    "endpoint": "/upload-endpoint",
>
    "method": "POST",
>
    "connected_account_id": "<CONNECTED_ACCOUNT_ID>",
>
    "binary_body": {
>
      "base64": "JVBERi0xLjQKJ...<base64_data>...",
>
      "content_type": "application/pdf"
>
    }
>
  }'

File Downloads (binary_data)

When the proxied request returns a binary response (for example, a PDF or image), the proxy automatically uploads the file to temporary storage, and you receive a signed URL in the binary_data field. This enables you to download large files securely.

File Download Request

$
curl --location 'https://backend.composio.dev/api/v3/tools/execute/proxy' \
>
  --header 'accept: application/json' \
>
  --header 'x-api-key: <YOUR_API_KEY>' \
>
  --header 'Content-Type: application/json' \
>
  --data '{
>
    "endpoint": "{YOUR_ENDPOINT}",
>
    "method": "GET",
>
    "connected_account_id": "{YOUR_CONNECTED_ACCOUNT_ID}"
>
  }'

File Download Response

1
{
2
  "data": {},
3
  "binary_data": {
4
    "url": "url to the file",
5
    "content_type": "content type of the file",
6
    "size": "size of the file",
7
    "expires_at": "expires at of the file"
8
  },
9
  "status": "status code of the response",
10
  "headers": "headers of the response"
11
}

Summary

We’d love your feedback on the new proxy execute capabilities. If anything feels unclear or you have suggestions for improvement, please reach out.