Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: update documentation for new changelog entries
github-actions[bot] committed
Sep 22, 2026 at 12:15 UTC
3435c3a41c2a3fb40ab7381513d71714560eb218
10 files changed
+81
-2
docs/content/docs/auth-configuration/connected-accounts.mdx
+14
@@ -88,6 +88,10 @@ To call a provider API, use [Proxy Execute](/docs/extending-sessions/proxy-execu
88
89
## Refresh credentials
90
91
+<Callout type="warn">
92
+`composio.connected_accounts.refresh()` in Python and `composio.connectedAccounts.refresh()` in TypeScript are deprecated. Re-initiate authentication with `link()` or `composio.toolkits.authorize()` instead. The refresh endpoint no longer validates credentials. TypeScript ignores `validateCredentials` and logs a warning when you set it.
93
+</Callout>
94
+
95
Manually refresh credentials for a connected account:
96
97
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
@@ -161,6 +165,16 @@ console.log('Account enabled status:', enabled.success);
165
INACTIVE accounts cannot execute tools. Tool execution will fail until the status is changed.
166
</Callout>
167
168
+## Revoke accounts
169
+
170
+To revoke upstream tokens and mark a connection `REVOKED`, call `composio.connected_accounts.revoke(connected_account_id)` in Python or `await composio.connectedAccounts.revoke(connectedAccountId)` in TypeScript. Upstream token revocation is best effort. The call fails if the toolkit does not support programmatic revocation or the account is not in a revokable state.
171
+
172
+## Complete deferred OAuth
173
+
174
+If your project has an OAuth callback verifier configured, Composio redirects to your verifier with a single-use session URI before activating the connection. Verify the person's identity in your application, then redeem the URI with `composio.connected_accounts.complete_auth(user_id=user_id, session_uri=session_uri)` in Python or `await composio.connectedAccounts.completeAuth({ userId, sessionUri })` in TypeScript.
175
+
176
+Composio checks project ownership and the connection's user ID before completing the token exchange. An expired or already redeemed URI returns a `404`.
177
+
178
## Delete accounts
179
180
Permanently remove a connected account:
docs/content/docs/authentication/controlling-scopes.mdx
+12
@@ -12,6 +12,18 @@ You control scopes on an [auth config](/docs/authentication#behind-the-scenes),
12
Scopes apply to OAuth toolkits. Toolkits that authenticate with API keys or bearer tokens don't have scopes to set.
13
</Callout>
14
15
+## Choose scopes for your tools
16
+
17
+Use `composio.toolkits.recommend_scopes("gmail", tools=["GMAIL_SEND_EMAIL"])` in Python or `await composio.toolkits.recommendScopes('gmail', { tools: ['GMAIL_SEND_EMAIL'] })` in TypeScript to find scopes for the tools your agent needs. The response includes a least-privilege set, a set with the fewest scopes, and conditional scopes. Pass `available_scopes` (Python) or `availableScopes` (TypeScript) to constrain recommendations to scopes your OAuth app can request.
18
+
19
+Recommendations can depend on account type or other grant contexts. Inspect the supported dimensions and defaults with `composio.toolkits.list_grant_contexts("gmail")` in Python or `await composio.toolkits.listGrantContexts('gmail')` in TypeScript, then pass your selections as `grant_context` or `grantContext` when requesting scopes.
20
+
21
+<Callout>
22
+Scope recommendations and grant-context APIs are experimental. Review the recommendation before using it in your auth config.
23
+</Callout>
24
+
25
+Toolkit auth details also expose `required_scopes` (Python) or `requiredScopes` (TypeScript): scopes the auth method always requests, regardless of tool-specific scopes. Auth fields expose `user_visible` or `userVisible` to indicate whether the hosted connection flow displays them. These fields may be absent when the API does not provide them.
26
+
27
## Set scopes with Composio managed auth
28
29
Pass a `scopes` field in `credentials` to override the defaults while still using Composio's managed OAuth app. Give scopes as a comma-separated string.
docs/content/docs/configuring-sessions.mdx
+8
@@ -825,6 +825,12 @@ do {
825
</Tab>
826
</Tabs>
827
828
+### Configuration history
829
+
830
+Inspect the configurations a session has used with `session.list_config_history(limit=10)` in Python or `await session.listConfigHistory({ limit: 10 })` in TypeScript. Results are newest first, with the live configuration first. Each `session.update()` archives the previous configuration.
831
+
832
+The response contains `items` with each version's `config` and an `is_current` (Python) or `isCurrent` (TypeScript) flag. Pass the response's `next_cursor` (Python) or `nextCursor` (TypeScript) as `cursor` to fetch another page; `limit` supports up to 100 items per page.
833
+
834
### delete()
835
836
Delete a session when you're done with it. Deleted sessions immediately stop being retrievable or executable, and the call returns the deleted `session_id`. Deleting a missing or already-deleted session surfaces the backend `404`.
@@ -907,6 +913,8 @@ console.log(tool.outputParameters);
913
</Tab>
914
</Tabs>
915
916
+To fetch several toolkits in one request, use `composio.toolkits.get_many(["github", "slack"])` in Python or `await composio.toolkits.getMany(['github', 'slack'])` in TypeScript. Both return the matching toolkits.
917
+
918
## Next
919
920
<Card icon={<Database />} title="Sandbox" href="/docs/sandbox/remote" description="Give sessions a persistent compute environment with COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL" />
docs/content/docs/extending-sessions/custom-mcp.mdx
+9
-2
@@ -24,7 +24,15 @@ A Custom MCP moves through this lifecycle:
24
5. **Use** the toolkit in a session. For authenticated servers, explicitly select the connected account.
25
26
<Callout type="warn" title="API-only while Custom MCP is experimental">
27
-Use the lifecycle endpoints below to register, sync, and delete Custom MCP toolkits. The SDKs don't expose these endpoints yet, and their contracts may change while Custom MCP is experimental. The API reference has the full request and response schemas for [upsert](/reference/api-reference/toolkits/postCustomToolkitsUpsert), [sync](/reference/api-reference/toolkits/postCustomToolkitsSync), and [delete](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug). Dashboard management is coming soon for customers who prefer a UI.
27
+Use the lifecycle endpoints below to register, sync, and delete Custom MCP toolkits. You can also use the experimental SDK methods described below. These contracts may change while Custom MCP is experimental. The API reference has the full request and response schemas for [upsert](/reference/api-reference/toolkits/postCustomToolkitsUpsert), [sync](/reference/api-reference/toolkits/postCustomToolkitsSync), and [delete](/reference/api-reference/toolkits/deleteCustomToolkitsBySlug). Dashboard management is coming soon for customers who prefer a UI.
28
+</Callout>
29
+
30
+### Manage custom toolkits with the SDK
31
+
32
+You can also run this lifecycle through `composio.experimental.custom_toolkits` in Python or `composio.experimental.customToolkits` in TypeScript. Both provide `upsert()` to register a toolkit or update its display metadata, `sync()` to fetch its remote tool definitions, and `delete()` to remove it and its associated auth configs and connections.
33
+
34
+<Callout>
35
+These project-owned toolkit APIs are experimental. They manage remote toolkits registered in Composio; [local custom toolkits](/docs/extending-sessions/custom-tools-and-toolkits) run in your SDK process.
36
</Callout>
37
38
## Register a Custom MCP
@@ -382,7 +390,6 @@ See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more example
390
<Accordions>
391
<Accordion title="Setup and lifecycle">
392
385
-- **API-only setup:** The SDKs don't expose registration, sync, update, or deletion methods yet. Use the lifecycle endpoints on this page, then use the toolkit slug through the SDK.
393
- **Dashboard coming soon:** Custom MCP management isn't available in the dashboard yet.
394
- **Remote servers only:** Composio doesn't host your server. Deploy it at a public HTTPS endpoint; local and STDIO-only servers aren't supported.
395
- **Immutable `app_url` and `auth_schemes`:** Re-registering an existing slug updates other fields in place, but changing `app_url` or `auth_schemes` returns `409 Conflict`. Delete the toolkit, then register it again. Deletion also removes its auth configurations and connected accounts.
docs/content/docs/poc-to-prod/stream-logs-to-a-siem.mdx
+6
@@ -34,6 +34,12 @@ To fetch the next page, pass `next_cursor` as `cursor` in the request body. Keep
34
35
The API accepts up to 100 records per page, and time ranges use epoch milliseconds. For targeted investigations, add [filters](/reference/api-reference/logs#filter-fields) such as `user_id`, `tool_slug`, or `status`. Leave filters unset when collecting all tool execution events.
36
37
+### Fetch logs with the SDK
38
+
39
+Both SDKs expose `composio.logs.search()` for read-only searches with filters, a time range, and cursor pagination. Python accepts keyword arguments such as `limit=100` and `time_range={"from": from_ms, "to": to_ms}`; TypeScript accepts an options object with `limit` and `timeRange`. Read the returned `logs` and pass `next_cursor` (Python) or `nextCursor` (TypeScript) as the next request's `cursor`.
40
+
41
+Retrieve the full entry for one execution with `composio.logs.get("log_123")` in Python or `await composio.logs.get('log_123')` in TypeScript.
42
+
43
## Schedule collection without losing your place
44
45
Run a collector for each project, with its own API key and durable checkpoint. A scheduled job or your platform's HTTP poller can perform these steps. If you use a poller, verify that it supports POST bodies, cursor pagination, and saved state.
docs/content/docs/production-readiness.mdx
+16
@@ -34,6 +34,8 @@ Use separate Composio projects for development, staging, and production when tho
34
35
Keep every project API key on the server. Store production keys in your deployment platform's secret manager, rotate them according to your security policy, and never expose them to browser or mobile clients.
36
37
+For user- or organization-scoped operations, pass `user_api_key` or `org_api_key` to the Python `Composio` constructor, or `userApiKey` or `orgApiKey` in TypeScript. You can also set `COMPOSIO_USER_API_KEY` and `COMPOSIO_ORG_API_KEY`. A project API key is still required. The client sends the scoped key only to operations that require it.
38
+
39
## 3. Decide how customers authenticate
40
41
Keep managed auth when its provider app, scopes, and quotas fit your product. It removes OAuth app setup and token-refresh work.
@@ -74,6 +76,20 @@ Run at least one safe, read-only call against a real connected account. Confirm
76
77
Do not treat a successful Connect Link alone as an end-to-end test. Authentication can succeed while a provider API, scope, or tool input still fails.
78
79
+### Configure SDK logging
80
+
81
+Pass `logger` and `logLevel` to the TypeScript `Composio` constructor to send SDK logs to your logging system. The logger must provide `error`, `warn`, `info`, and `debug` methods. Messages have credential-shaped values redacted before reaching the logger, including owned-client deprecation warnings. Logger configuration is process-wide: the last configured instance controls the SDK logger.
82
+
83
+In Python, pass a standard `logging.Logger` as `logger` and a `composio.utils.logging.LogLevel` as `logging_level`. Sensitive values are redacted before records reach the logger. Deprecation notices use `ComposioDeprecationWarning` warnings rather than log records.
84
+
85
+### Inspect project usage
86
+
87
+Use `composio.experimental.usage.summary()` for totals by entity type and `composio.experimental.usage.breakdown()` for grouped usage of one entity type, such as `tool_calls` or `sessions`. Both SDKs scope these queries to the project associated with your API key.
88
+
89
+<Callout>
90
+Usage metering is experimental, and its response shape may change.
91
+</Callout>
92
+
93
## 7. Verify triggers through your real webhook
94
95
If your product uses triggers, test the deployed HTTPS webhook rather than only a local callback. Parse events with the Composio SDK, verify the payload reaches the correct environment, and map it to the expected user or workspace before doing work.
docs/content/docs/security/token-custody.mdx
+4
@@ -119,6 +119,10 @@ The [customer-managed key architecture](https://composio.dev/blog/two-questions-
119
120
If your requirement is that Composio cannot decrypt provider credentials, evaluate the customer-managed key arrangement with the team. For VPC or self-hosted deployments, confirm who operates each service, who can decrypt credentials, where logs and backups reside, and which outbound connections are required. A deployment label alone does not answer those questions. [Contact Composio](https://composio.dev/contact?utm_source=docs) to establish the architecture and contractual requirements.
121
122
+### Customer-managed keyring transfer keys
123
+
124
+If your organization has an active customer-managed keyring, retrieve its public transfer keys with `composio.keyring.list_transfer_keys()` in Python or `await composio.keyring.listTransferKeys()` in TypeScript. Use the key identified by `active_kid` (Python) or `activeKid` (TypeScript) when sealing new secrets for transfer. The API returns `404` if your organization has no active keyring.
125
+
126
## Application authorization and retained data
127
128
Your backend must bind the signed-in user to the correct Composio `user_id` and connected accounts. A caller-supplied user ID is not proof of identity. Choose [provider scopes](/docs/authentication/controlling-scopes), [session tools](/docs/configuring-sessions), and [API-key permissions](/reference/authenticating-to-composio/project-api-key-permissions) for the operations your application needs.
docs/content/docs/setting-up-triggers/custom-oauth-webhooks.mdx
+2
@@ -31,6 +31,8 @@ Every inbound event is signature-checked at ingress before any trigger fires:
31
**Sharing one OAuth app across projects?** Consolidate to a single project or register separate OAuth apps per project before continuing.
32
</Callout>
33
34
+You can also manage ingress endpoints through `composio.webhooks.endpoints` in either SDK. Use `list()` and `get()` to inspect endpoints, `create()` to register one, and `replace()` or `update()` to change its configuration.
35
+
36
The walkthrough below uses Slack as the example and the [Webhook Endpoints API](/reference/api-reference/webhook-endpoints). For setup notes specific to each toolkit, see its FAQ section, for example [Slack](/toolkits/slack) or [Notion](/toolkits/notion).
37
38
## Step 1: Discover what credentials the endpoint needs
docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+6
@@ -145,6 +145,12 @@ console.log(`Delivering events to ${subscription.webhookUrl}`);
145
146
Your webhook endpoint must be publicly reachable. Composio's outbound IPs are dynamic, so IP allowlists and VPN-only endpoints won't work. Authenticate payloads with [signature verification](#verifying-signatures) instead.
147
148
+### Manage project subscriptions
149
+
150
+Use `composio.webhooks.subscriptions` to manage outbound delivery from your project. Both SDKs provide `list()`, `get()`, `set()`, `update()`, and `delete()`. Rotate signing secrets with `rotate_secret()` in Python or `rotateSecret()` in TypeScript, and discover supported events with `list_event_types()` or `listEventTypes()`.
151
+
152
+For inbound events from a provider's OAuth app, use [webhook endpoints](/docs/setting-up-triggers/custom-oauth-webhooks).
153
+
154
## Handling events
155
156
In your handler, pass the incoming request to `parse()`. It returns the typed, normalized payload. Pass `verifySecret` and it verifies the signature first, so one call both authenticates and parses.
docs/content/docs/tools-direct/toolkit-versioning.mdx
+4
@@ -197,6 +197,10 @@ console.log("Latest Version:", toolkit.meta.availableVersions?.[0]);
197
</Tab>
198
</Tabs>
199
200
+### Retrieve toolkit changelogs
201
+
202
+Call `composio.toolkits.changelog()` in Python or `await composio.toolkits.changelog()` in TypeScript to retrieve the last 10 versions for each toolkit. The response's `items` contain each toolkit's slug and version entries, which you can review before changing a pinned version.
203
+
204
## Next
205
206
<Card icon={<Wrench />} title="Fetching tools" href="/docs/tools-direct/fetching-tools" description="Fetch and filter tools, inspect schemas, and search semantically" />