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: categorize FAQs into logical sections for easier navigation
Co-Authored-By: palash <palash@composio.dev>
Devin AI committed
Mar 13, 2026 at 06:49 UTC
5b4e5f5e6bdcf3f31a7f544c5a5c38773e01c5ab
1 file changed
+113
-80
docs/content/docs/common-faq.mdx
+113
-80
@@ -4,38 +4,50 @@ description: Frequently asked questions about Composio
4
keywords: [faq, questions, help, common questions]
5
---
6
7
+## General
8
+
9
<Accordions>
10
9
-<Accordion title="Can I white label Composio's auth screens?">
10
-Yes. By default, OAuth consent screens show "Composio" as the app name. If you create an auth config with your own OAuth client ID and secret, users will see your app's name and logo instead.
11
+<Accordion title="Do I need an AI agent to use Composio?">
12
+No. If you're building an AI agent, Composio can give it [meta tools](/docs/quickstart) that handle tool discovery and execution automatically, or you can [fetch specific tools](/docs/tools-direct/fetching-tools) and pass them to your agent directly.
13
12
-You can also proxy the OAuth redirect through your own domain so users never see `backend.composio.dev` in the URL bar. See [White-labeling authentication](/docs/white-labeling-authentication).
14
+If you don't have an agent, you can [execute tools directly](/docs/tools-direct/executing-tools#direct-tool-execution) from any backend.
15
</Accordion>
16
15
-<Accordion title="Is white labeling available on the free plan?">
16
-Yes. White labeling works on all plans, including free. You can create custom auth configs with your own OAuth credentials on any account. See [White-labeling authentication](/docs/white-labeling-authentication).
17
-</Accordion>
17
+<Accordion title="What is the difference between a tool and a toolkit?">
18
+A **toolkit** is a collection of related tools grouped by app, for example the GitHub toolkit or the Gmail toolkit. A **tool** is a single action within a toolkit, like `GITHUB_CREATE_ISSUE` or `GMAIL_SEND_EMAIL`.
19
19
-<Accordion title="How do I hide the Composio logo during authentication?">
20
-Go to your [project settings](https://platform.composio.dev/settings) and upload your own logo and app title. This replaces Composio branding on the Connect Link page. To also remove "Composio" from OAuth consent screens (Google, GitHub, Slack, etc.), create a custom auth config with your own OAuth credentials. See [White-labeling authentication](/docs/white-labeling-authentication) for the full guide.
20
+You connect to toolkits (via OAuth or API keys), and then execute individual tools within them. See [Tools and toolkits](/docs/tools-and-toolkits).
21
</Accordion>
22
23
-<Accordion title="I changed my branding but still see 'Secured by Composio'">
24
-The Connect Link logo and app title customization does not remove the "Secured by Composio" badge. To remove it, you need to set up your own OAuth app by creating a [custom auth config](/docs/white-labeling-authentication#using-your-own-oauth-apps) with your own client ID and secret.
23
+<Accordion title="What is User ID and how should I use it?">
24
+The User ID is how Composio identifies your end users. It maps each user to their connected accounts and sessions. Use any unique identifier from your system, like an email, database ID, or UUID.
25
+
26
+When you create a session with `composio.create(user_id="user_123")`, all connected accounts and tool executions are scoped to that user. See [Users and sessions](/docs/users-and-sessions).
27
</Accordion>
28
27
-<Accordion title="What is the difference between a tool and a toolkit?">
28
-A **toolkit** is a collection of related tools grouped by app, for example the GitHub toolkit or the Gmail toolkit. A **tool** is a single action within a toolkit, like `GITHUB_CREATE_ISSUE` or `GMAIL_SEND_EMAIL`.
29
+<Accordion title="What is the difference between an auth config and an MCP config in the dashboard?">
30
+An **auth config** defines how users authenticate with a toolkit (OAuth credentials, scopes, API keys). You need one whenever you want users to connect to an app.
31
30
-You connect to toolkits (via OAuth or API keys), and then execute individual tools within them. See [Tools and toolkits](/docs/tools-and-toolkits).
31
-</Accordion>
32
+An **MCP config** creates a hosted MCP server that exposes specific tools over the Model Context Protocol. It's only needed if you're connecting to Composio from an MCP client like Claude Desktop, Cursor, or OpenAI's Responses API via MCP.
33
33
-<Accordion title="Do I need an AI agent to use Composio?">
34
-No. If you're building an AI agent, Composio can give it [meta tools](/docs/quickstart) that handle tool discovery and execution automatically, or you can [fetch specific tools](/docs/tools-direct/fetching-tools) and pass them to your agent directly.
34
+**If you're using the Composio SDK** (sessions or direct execution), you only need auth configs. The SDK handles tool delivery natively. You don't need to create an MCP config.
35
36
-If you don't have an agent, you can [execute tools directly](/docs/tools-direct/executing-tools#direct-tool-execution) from any backend.
36
+**If you're using an MCP client**, you need both: an auth config (so users can authenticate) and an MCP config (so the client can discover and call tools over the MCP protocol).
37
+
38
+See [Native Tools vs MCP](/docs/native-tools-vs-mcp) for a full comparison.
39
</Accordion>
40
41
+<Accordion title="When should I create a new session?">
42
+Create a new session when the config changes: different toolkits, different auth config, or a different connected account. You don't need to store or manage session IDs. Just call `create()` each time. See [Users and sessions](/docs/users-and-sessions).
43
+</Accordion>
44
+
45
+</Accordions>
46
+
47
+## Tools & Toolkits
48
+
49
+<Accordions>
50
+
51
<Accordion title="Where can I see all available toolkits?">
52
You can browse all toolkits on the [Toolkits page](/toolkits) in the docs or in the [Composio dashboard](https://platform.composio.dev?next_page=/marketplace). Both list every supported app along with available auth schemes and tools.
53
</Accordion>
@@ -76,24 +88,37 @@ You can also list the toolkits available in a session with `session.toolkits()`.
88
You can request new tools or toolkits on the [tool request board](https://request.composio.dev/boards/tool-requests). The team reviews requests regularly.
89
</Accordion>
90
79
-<Accordion title="What is User ID and how should I use it?">
80
-The User ID is how Composio identifies your end users. It maps each user to their connected accounts and sessions. Use any unique identifier from your system, like an email, database ID, or UUID.
91
+<Accordion title="How do I work with toolkit versions?">
92
+Composio toolkits are versioned using date-based identifiers (e.g., `20251027_00`). You can pin versions at SDK initialization or per tool execution to keep behavior consistent across deployments.
93
82
-When you create a session with `composio.create(user_id="user_123")`, all connected accounts and tool executions are scoped to that user. See [Users and sessions](/docs/users-and-sessions).
94
+This applies to direct tool execution only. Sessions with meta tools always use the latest version. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).
95
</Accordion>
96
85
-<Accordion title="What is the difference between an auth config and an MCP config in the dashboard?">
86
-An **auth config** defines how users authenticate with a toolkit (OAuth credentials, scopes, API keys). You need one whenever you want users to connect to an app.
97
+<Accordion title="Why does the API return fewer tools than the platform UI?">
98
+When calling the Get Tools API (`GET /api/v3/tools`) without specifying a `toolkit_versions` parameter, the API defaults to the base version (`00000000_00`), which only includes tools from the initial release. The platform UI shows tools from the latest version.
99
88
-An **MCP config** creates a hosted MCP server that exposes specific tools over the Model Context Protocol. It's only needed if you're connecting to Composio from an MCP client like Claude Desktop, Cursor, or OpenAI's Responses API via MCP.
100
+To get all available tools, pass `toolkit_versions=latest`:
101
90
-**If you're using the Composio SDK** (sessions or direct execution), you only need auth configs. The SDK handles tool delivery natively. You don't need to create an MCP config.
102
+```bash
103
+curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \
104
+ -H 'x-api-key: YOUR_API_KEY'
105
+```
106
92
-**If you're using an MCP client**, you need both: an auth config (so users can authenticate) and an MCP config (so the client can discover and call tools over the MCP protocol).
107
+See [Toolkit versioning](/docs/tools-direct/toolkit-versioning) for more details.
108
+</Accordion>
109
94
-See [Native Tools vs MCP](/docs/native-tools-vs-mcp) for a full comparison.
110
+<Accordion title="Does Composio support triggers?">
111
+Yes. Triggers let you listen for events from connected apps, like a new email in Gmail, a new issue in GitHub, or a new message in Slack. When the event fires, Composio sends a webhook to your endpoint with the event payload.
112
+
113
+See [Triggers](/docs/triggers) for setup and [Subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events) for receiving events.
114
</Accordion>
115
116
+</Accordions>
117
+
118
+## Authentication & Connections
119
+
120
+<Accordions>
121
+
122
<Accordion title="What is an auth config?">
123
An auth config is a blueprint that defines how authentication works for a toolkit. It specifies the auth method (OAuth2, API Key, etc.), the scopes to request, and the credentials to use.
124
@@ -108,25 +133,6 @@ Composio supports **OAuth2**, **OAuth1**, **API Key**, **Bearer Token**, and **B
133
For toolkits with Composio-managed auth, you don't need to configure anything. For toolkits without it, you'll need to create a [custom auth config](/docs/using-custom-auth-configuration). See [Authentication](/docs/authentication) for the full overview.
134
</Accordion>
135
111
-<Accordion title="How do I work with toolkit versions?">
112
-Composio toolkits are versioned using date-based identifiers (e.g., `20251027_00`). You can pin versions at SDK initialization or per tool execution to keep behavior consistent across deployments.
113
-
114
-This applies to direct tool execution only. Sessions with meta tools always use the latest version. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).
115
-</Accordion>
116
-
117
-<Accordion title="Why does the API return fewer tools than the platform UI?">
118
-When calling the Get Tools API (`GET /api/v3/tools`) without specifying a `toolkit_versions` parameter, the API defaults to the base version (`00000000_00`), which only includes tools from the initial release. The platform UI shows tools from the latest version.
119
-
120
-To get all available tools, pass `toolkit_versions=latest`:
121
-
122
-```bash
123
-curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit_versions=latest' \
124
- -H 'x-api-key: YOUR_API_KEY'
125
-```
126
-
127
-See [Toolkit versioning](/docs/tools-direct/toolkit-versioning) for more details.
128
-</Accordion>
129
-
136
<Accordion title="Can a user connect multiple accounts for the same app?">
137
Yes. For example, a user can connect both a personal and work Gmail account. Call `session.authorize()` multiple times for the same toolkit. Each session uses the most recently connected account by default, but you can pin a specific account when creating the session.
138
@@ -139,26 +145,6 @@ Composio automatically refreshes OAuth tokens before they expire. You don't need
145
If a refresh fails permanently (e.g., the user revoked access or the OAuth app was deleted), the connection status changes to `EXPIRED`. You can [subscribe to expiry events](/docs/subscribing-to-connection-expiry-events) to detect this and prompt users to re-authenticate. See [Connection statuses](/docs/tools-direct/authenticating-tools#connection-statuses) for more details.
146
</Accordion>
147
142
-<Accordion title="Does Composio support triggers?">
143
-Yes. Triggers let you listen for events from connected apps, like a new email in Gmail, a new issue in GitHub, or a new message in Slack. When the event fires, Composio sends a webhook to your endpoint with the event payload.
144
-
145
-See [Triggers](/docs/triggers) for setup and [Subscribing to triggers](/docs/setting-up-triggers/subscribing-to-events) for receiving events.
146
-</Accordion>
147
-
148
-<Accordion title="Why are my connected account secrets showing `abcd...` or `REDACTED`?">
149
-Connected account secrets are masked by default for security. The API returns the first 4 characters followed by `...` (e.g., `gho_...`). Values shorter than 4 characters show as `REDACTED`.
150
-
151
-To disable masking, go to **Settings → Project Settings → Project Configuration** and turn off "Mask Connected Account Secrets", or use the Patch Project Config API.
152
-
153
-See [Connected accounts](/docs/auth-configuration/connected-accounts#get-account-credentials) for full details.
154
-</Accordion>
155
-
156
-<Accordion title="Where can I find execution logs?">
157
-Every tool execution is logged in the [Composio dashboard](https://platform.composio.dev?next_page=/logs/tools) under **Logs > Tools**. Each execution response includes a `log_id` you can use to look up detailed request and response data. Trigger delivery attempts are logged separately under **Logs > Triggers**.
158
-
159
-See [Troubleshooting tools](/docs/troubleshooting/tools) for how to use logs to debug failed executions.
160
-</Accordion>
161
-
148
<Accordion title="How do I redirect users back to my app after they connect?">
149
Pass a `callbackUrl` when calling `link()`, `initiate()`, or `session.authorize()`. After authentication, Composio redirects the user to that URL with `status=success` or `status=failed` and the `connected_account_id` appended as query parameters.
150
@@ -200,21 +186,6 @@ const connection = await composio.connectedAccounts.initiate('user_123', 'your_a
186
Each user gets their own connected account scoped to their `user_id`, but they all share your API key under the hood. See [API key connections](/docs/tools-direct/authenticating-tools#api-key-connections) for the full setup.
187
</Accordion>
188
203
-<Accordion title="Is Composio secure? Where can I find compliance details?">
204
-Yes. Composio is SOC 2 Type II compliant and follows industry-standard security practices for data handling, encryption, and access control. Visit the [Composio Trust Center](https://trust.composio.dev/) for detailed compliance reports, security policies, and certifications.
205
-</Accordion>
206
-
207
-<Accordion title="What is the IP range for Composio's MCP servers?">
208
-Composio does not have fixed IP ranges. Traffic is routed through Cloudflare and Vercel, which use dynamic IPs.
209
-</Accordion>
210
-
211
-<Accordion title="How do I increase my quota?">
212
-Upgrade your plan. See [pricing](https://composio.dev/pricing) for available plans and limits.
213
-</Accordion>
214
-<Accordion title="When should I create a new session?">
215
-Create a new session when the config changes: different toolkits, different auth config, or a different connected account. You don't need to store or manage session IDs. Just call `create()` each time. See [Users and sessions](/docs/users-and-sessions).
216
-</Accordion>
217
-
189
<Accordion title="How do I configure sessions with custom auth configs?">
190
Some toolkits require your own OAuth credentials or API keys. Create an auth config in the dashboard by selecting the toolkit, choosing the auth scheme, and entering your credentials. Then pass the auth config ID when creating a session using the `auth_configs` (or `auth_config_id`) parameter so the session uses your developer credentials instead of Composio-managed auth. See [Using custom auth configuration](/docs/using-custom-auth-configuration).
191
</Accordion>
@@ -255,6 +226,50 @@ This applies whether you're using sessions or direct tool execution:
226
- **Direct tool execution:** Pass the new `authConfigId` when calling `initiate()`. See [Switching auth configs (direct)](/docs/auth-configuration/white-labeling#switching-from-composio-managed-to-your-own-oauth-app).
227
</Accordion>
228
229
+</Accordions>
230
+
231
+## White Labeling & Branding
232
+
233
+<Accordions>
234
+
235
+<Accordion title="Can I white label Composio's auth screens?">
236
+Yes. By default, OAuth consent screens show "Composio" as the app name. If you create an auth config with your own OAuth client ID and secret, users will see your app's name and logo instead.
237
+
238
+You can also proxy the OAuth redirect through your own domain so users never see `backend.composio.dev` in the URL bar. See [White-labeling authentication](/docs/white-labeling-authentication).
239
+</Accordion>
240
+
241
+<Accordion title="Is white labeling available on the free plan?">
242
+Yes. White labeling works on all plans, including free. You can create custom auth configs with your own OAuth credentials on any account. See [White-labeling authentication](/docs/white-labeling-authentication).
243
+</Accordion>
244
+
245
+<Accordion title="How do I hide the Composio logo during authentication?">
246
+Go to your [project settings](https://platform.composio.dev/settings) and upload your own logo and app title. This replaces Composio branding on the Connect Link page. To also remove "Composio" from OAuth consent screens (Google, GitHub, Slack, etc.), create a custom auth config with your own OAuth credentials. See [White-labeling authentication](/docs/white-labeling-authentication) for the full guide.
247
+</Accordion>
248
+
249
+<Accordion title="I changed my branding but still see 'Secured by Composio'">
250
+The Connect Link logo and app title customization does not remove the "Secured by Composio" badge. To remove it, you need to set up your own OAuth app by creating a [custom auth config](/docs/white-labeling-authentication#using-your-own-oauth-apps) with your own client ID and secret.
251
+</Accordion>
252
+
253
+</Accordions>
254
+
255
+## Debugging & Troubleshooting
256
+
257
+<Accordions>
258
+
259
+<Accordion title="Why are my connected account secrets showing `abcd...` or `REDACTED`?">
260
+Connected account secrets are masked by default for security. The API returns the first 4 characters followed by `...` (e.g., `gho_...`). Values shorter than 4 characters show as `REDACTED`.
261
+
262
+To disable masking, go to **Settings → Project Settings → Project Configuration** and turn off "Mask Connected Account Secrets", or use the Patch Project Config API.
263
+
264
+See [Connected accounts](/docs/auth-configuration/connected-accounts#get-account-credentials) for full details.
265
+</Accordion>
266
+
267
+<Accordion title="Where can I find execution logs?">
268
+Every tool execution is logged in the [Composio dashboard](https://platform.composio.dev?next_page=/logs/tools) under **Logs > Tools**. Each execution response includes a `log_id` you can use to look up detailed request and response data. Trigger delivery attempts are logged separately under **Logs > Triggers**.
269
+
270
+See [Troubleshooting tools](/docs/troubleshooting/tools) for how to use logs to debug failed executions.
271
+</Accordion>
272
+
273
<Accordion title="How do I check complete logs / API calls from the SDK?">
274
Enable debug logging to view all API calls and network requests made by the SDK.
275
@@ -271,6 +286,24 @@ COMPOSIO_LOG_LEVEL=debug
286
See [Troubleshooting SDKs](/docs/troubleshooting/sdks).
287
</Accordion>
288
289
+</Accordions>
290
+
291
+## Platform & Pricing
292
+
293
+<Accordions>
294
+
295
+<Accordion title="Is Composio secure? Where can I find compliance details?">
296
+Yes. Composio is SOC 2 Type II compliant and follows industry-standard security practices for data handling, encryption, and access control. Visit the [Composio Trust Center](https://trust.composio.dev/) for detailed compliance reports, security policies, and certifications.
297
+</Accordion>
298
+
299
+<Accordion title="What is the IP range for Composio's MCP servers?">
300
+Composio does not have fixed IP ranges. Traffic is routed through Cloudflare and Vercel, which use dynamic IPs.
301
+</Accordion>
302
+
303
+<Accordion title="How do I increase my quota?">
304
+Upgrade your plan. See [pricing](https://composio.dev/pricing) for available plans and limits.
305
+</Accordion>
306
+
307
<Accordion title="Can Composio be self-hosted?">
308
Yes, Composio supports self-hosting on the Enterprise plan. See [pricing](https://composio.dev/pricing) for details or [talk to us](https://calendly.com/composiohq/enterprise).
309
</Accordion>