Composio Release Notes

What's Changed

• fix(python-sdk): handle file upload list unions by @shreysingla11 in #3373
• docs(py): add 0.13.1 entry to CHANGELOG by @jkomyno in #3427
• fix(ts-sdk): handle file upload list unions by @shreysingla11 in #3374
• docs: add Shared Connections page under Authentication by @venkat82 in #3406
• feat(cli): refresh approval fallback page by @CryogenicPlanet in #3431

Full Changelog

https://github.com/ComposioHQ/composio/compare/@composio/[email protected]...@composio/[email protected]

What's in 0.13.1

Adds a 0.13.1 entry to python/CHANGELOG.md covering the changes accumulated on next since the last Python release ([email protected], May 7).

The CHANGELOG had been quietly abandoned since 0.8.11 (Sept 2025); rather than try to backfill the 4-minor gap, this PR draws a line and adds a banner pointing readers at the git log for that window. Future releases start fresh from here.

• SHARED connected accounts (experimental) — composio.experimental.update_acl, experimental={...} on link() / session.authorize(), account_type filter on list(). Mirrors @composio/[email protected] shipping in #3425.
• initiate() deprecation warning — gated on response Deprecation header (RFC 9745) instead of auth_scheme, eliminating false positives for custom auth configs and non-OAuth schemes.
• Schema converter — preserves nullability on null-only anyOf blocks.
• Dep bump — composio-client 1.36.0 → 1.39.0.

Release plan

Documentation only — does NOT trigger a release on its own. The Python release flow is tag-triggered:

# After this PR merges and after #3425 ships:
git tag [email protected] <next HEAD sha>
git push origin [email protected]

That fires .github/workflows/py.release.yml which builds and publishes to PyPI.

🤖 Generated with Claude Code

Co-authored-by: jkomyno [email protected]

You can now programmatically revoke a connected account's OAuth 2.0 tokens at the upstream provider, giving you explicit control over when credentials are killed at the third-party — instead of relying on deletion or natural token expiry.

On success, the connection transitions to REVOKED and the response reports which token subjects were killed at the provider on this call.

Example request

curl -X POST 'https://backend.composio.dev/api/v3.1/connected_accounts/ca_1a2b3c4d5e6f/revoke' \
--header 'x-api-key: <YOUR_API_KEY>'

Example response (200 OK)

{
  "revoked_tokens": ["access_token", "refresh_token"],
  "connected_account": {
    "id": "ca_1a2b3c4d5e6f",
    "status": "REVOKED"
  }
}

The revoked_tokens array lists the subjects revoked at the provider during this call. An empty array means the connection was already in a revoked state and no upstream dispatch was issued.

Status Codes

• 200: Connection revoked (or already revoked — see revoked_tokens)
• 400: Revoke is not supported for this toolkit
• 404: Connected account does not exist
• 409: Connection is not in a revokable state (only ACTIVE and already-REVOKED are accepted)
• 500: Server error — revocation could not be completed

Revoke Is Not Automatic on Delete

Deleting a connected account or a project does not revoke tokens at the upstream provider — the credentials are removed from Composio but may remain live at the third-party until they expire naturally. If you need credentials killed at the provider, follow revoke-then-delete semantics: call POST /revoke first, then issue the delete.

Revoke Is Best-Effort

Some providers do not expose a programmatic way to revoke one or both token subjects (for example, an access token but no refresh-token revoke route, or no revoke endpoint at all). In those cases, Composio revokes whatever the provider supports and the revoked_tokens array reflects exactly what was killed. Always read revoked_tokens to confirm which subjects were affected — do not assume both access_token and refresh_token were revoked on every call.

Externally Revoked Tokens

If a user revokes the connection directly with the provider (for example, removing the app from their account on the provider's website), the upstream revoke call from this endpoint may return an error. Handle this case by treating the connection as already revoked on your side.

composio.create() now returns a new session ID on every call, even for identical configs, for better isolation and observability. For multi-turn conversations, store the session ID and reuse it with composio.use().

Custom tools can also be attached when reusing a session. See Reusing a session and Custom tools.

Modify a session's toolkits, auth configs, connected accounts, and other settings without creating a new session.

Only the fields you pass are changed:

connectedAccounts (TypeScript) and connected_accounts (Python) now accept an array of connected account IDs per toolkit. A single string is still accepted for backwards compatibility and is automatically coerced to an array.

Only one account per toolkit is allowed when multi-account mode is disabled.

SDK versions

• TypeScript @composio/core: 0.9.1
• Python composio: 0.13.0

Sessions now support preloading frequently used tools into session.tools() and the session MCP tool list, so agents can call them without searching each time.

This works for Composio-managed tools, while SDK custom tools can be exposed directly from session.tools() with preload: true.

Keep the preloaded set focused, generally fewer than 20 tools, to avoid context bloat.

SDK versions:

• TypeScript @composio/core: 0.9.0
• Python composio: 0.13.0

Direct tools preset:

Specialized agents with a narrow tool set can use the direct tools preset to load every tool allowed by session filters into the session's tool list and disable session meta tools by default.

For agents that still need selected helper behavior, supported meta tool groups can be enabled alongside the preset.

See Preloading tools, Direct tools preset, and Preloading custom tools for Python examples and full guidance.

composio.connectedAccounts.link() (TypeScript) and composio.connected_accounts.link() (Python) now match the multi-connection guard that initiate() already had. With Composio-managed redirectable-OAuth callers being migrated off POST /api/v3/connected_accounts onto POST /api/v3/connected_accounts/link, the guard moves with them — so the migration doesn't quietly drop the duplicate-connection check.

Behavior change

• Before: link() would happily create a second ACTIVE connection for the same (user_id, auth_config_id) pair without checking for an existing ACTIVE connection first.
• After: link() first calls connectedAccounts.list({ userIds, authConfigIds, statuses: ['ACTIVE'] }). If any active connection exists, link() throws ComposioMultipleConnectedAccountsError unless the caller passes allowMultiple: true (TypeScript) / allow_multiple=True (Python).

SDK versions (patch releases)

• TypeScript @composio/core: v0.8.1
• Python composio: v0.12.1

Migration

• Most callers don't need to do anything — link() raised an unrelated error or succeeded by accident in the duplicate-connection case before, and now raises a typed error you can handle.
• Two scenarios that need attention:
  1. You intentionally create multiple connections per (user, auth_config) — for example, two Gmail accounts for the same user. Opt in by passing allow_multiple=True.
  2. You're migrating from initiate() to link() as part of the Composio-managed OAuth migration. Pass allow_multiple through unchanged — same flag name, same default (False), same exception (ComposioMultipleConnectedAccountsError).

Webhook Triggers V2 introduces a first-class webhook_endpoints resource with a dedicated ingress URL per OAuth app. V2 is opt-in and scoped to new trigger slugs — existing V1 triggers, URLs, and payload formats are unchanged.

Summary

• New webhook_endpoints API: None (opt-in)
• New ingress path /api/v3.1/webhook_ingress/{toolkit}/{we_*}/trigger_event: None (opt-in)
• Ingress-level signature verification: Automatic for V2 endpoints
• New Slack V2 slugs (SLACK_CHANNEL_MESSAGE_RECEIVED, SLACK_DIRECT_MESSAGE_RECEIVED, SLACK_MESSAGE_REACTION_ADDED): Opt-in
• V1 ingress path and all legacy trigger slugs: None — unchanged

What's in V2

• Dedicated endpoint per OAuth app, keyed by (toolkit_slug, project_id, client_id) and exposes its own URL containing a random we_* identifier.
• Signature verification at ingress using HMAC-SHA256, Ed25519, or shared-token matching depending on the toolkit.
• Per-user authorization for app-level events on toolkits with per-user visibility (Slack first).
• Automatic handshakes and cleanup for provider verification challenges.

API reference

• All endpoints require a project API key (x-api-key).
• Methods include GET, POST, PATCH, DELETE for webhook subscriptions and endpoints.

Migration walkthrough (Slack)

• Slack is the first toolkit on V2.
• Steps include discovering required fields, creating the endpoint, storing the signing secret, adding an app-level token for private-scope events, pointing your Slack app at the V2 URL, and creating V2 trigger instances.

Heads up: OAuth apps are project-scoped on V2. Action required if you share a single OAuth app across multiple Composio projects or organizations today.

Backward compatibility

• Your V1 endpoints are unaffected.
• Existing trigger slugs continue to route through V1.
• You only need to set up a V2 webhook endpoint in two cases: to use new V2 trigger slugs or to move an OAuth app shared across multiple projects onto V2.