Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 03:15 UTC
docs: reframe guide as when-to-use, add FAQ, fix terminology
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sushmitha Mallesh committed
Mar 9, 2026 at 19:05 UTC
b9e9e51dba261e5bc0d694582121c5baa8dd1996
1 file changed
+81
-43
docs/content/docs/custom-app-vs-managed-app.mdx
+81
-43
@@ -1,44 +1,21 @@
1
---
2
-title: Custom App vs Composio Managed App
3
-description: When to use your own OAuth app credentials vs Composio's managed authentication
4
-keywords: [custom app, managed app, oauth, auth config, white label, own developer app, decision]
2
+title: When to use your own developer credentials
3
+description: When to use your own OAuth credentials instead of Composio managed authentication
4
+keywords: [custom auth config, managed auth, oauth, auth config, white label, own developer credentials, decision]
5
---
6
7
-**Composio managed apps** handle OAuth for you. Composio registers and maintains OAuth apps for popular toolkits (GitHub, Gmail, Slack, etc.) so you can start building immediately with no OAuth setup.
7
+Composio supports two ways to authenticate users with toolkits. You can use them together, and most production apps do.
8
9
-**Custom apps** use your own OAuth credentials. You register an OAuth app in the toolkit's developer portal and tell Composio to use your client ID and secret instead of the managed ones.
9
+- **Composio managed apps**: Composio registers and maintains OAuth apps for popular toolkits (GitHub, Gmail, Slack, etc.). Zero setup, works out of the box.
10
+- **Your own OAuth apps**: You register an OAuth app in the toolkit's developer portal and tell Composio to use your credentials instead.
11
11
-## Quick decision
12
+## When to use Composio managed apps
13
13
-Use **Composio managed apps** when:
14
-- You're prototyping, testing, or in early development
15
-- You don't need your branding on OAuth consent screens
16
-- Default scopes are sufficient
17
-- You want the fastest path to a working integration
14
+Managed apps are the default. Every toolkit that supports OAuth has a Composio managed app ready to go. Use them when:
15
19
-Use **your own custom app** when:
20
-- You're going to production with real users
21
-- Users should see your app name on consent screens, not "Composio"
22
-- You need custom OAuth scopes beyond Composio's defaults
23
-- You need dedicated API rate limits (managed apps share quota across all Composio users)
24
-- You're connecting to a self-hosted or regional instance (e.g., custom Salesforce subdomain)
25
-- Enterprise customers require your branding end-to-end
26
-
27
-## Comparison
28
-
29
-| | Composio Managed App | Custom App |
30
-|---|---|---|
31
-| **Setup** | Zero config. Works out of the box | Register OAuth app, get client ID/secret, create auth config |
32
-| **Consent screen** | Shows "Composio" | Shows your app name |
33
-| **OAuth scopes** | Composio's defaults | You choose exactly which scopes to request |
34
-| **Rate limits** | Shared across all Composio users | Dedicated to your app |
35
-| **Token management** | Composio handles refresh | Composio handles refresh (same) |
36
-| **Maintenance** | Composio maintains the OAuth app | You maintain your OAuth app registration |
37
-| **Cost** | Free, included | Free on Composio's side, but you manage the OAuth app |
38
-
39
-## How to use Composio managed apps
40
-
41
-No setup needed. Create a session and Composio uses managed auth automatically:
16
+- **You're building and iterating.** No OAuth app registration, no credentials to manage. Create a session and start testing immediately.
17
+- **Default scopes cover your needs.** Composio requests sensible defaults for each toolkit.
18
+- **Branding on consent screens doesn't matter.** Users will see "Composio wants to access your account" during OAuth. Fine for internal tools, prototypes, and development.
19
20
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
21
<Tab value="Python">
@@ -61,9 +38,15 @@ const session = await composio.create("user_123");
38
</Tab>
39
</Tabs>
40
64
-When a user needs to connect, the OAuth consent screen will show "Composio" as the requesting application.
41
+## When to use your own OAuth app
42
+
43
+Bring your own credentials when any of these apply:
44
66
-## How to use your own custom app
45
+- **Your users see OAuth consent screens.** In production, users should see your app name, not "Composio." This is the most common reason to switch.
46
+- **You need custom scopes.** Composio's default scopes may not include everything you need (e.g., write access to a specific Google API).
47
+- **You're hitting rate limits.** Managed apps share quota across all Composio users. Your own app gets a dedicated quota.
48
+- **You're connecting to a custom instance.** Self-hosted or regional variants (e.g., a private Salesforce subdomain) need their own OAuth app.
49
+- **Enterprise customers require your branding end-to-end.**
50
51
<Steps>
52
<Step>
@@ -128,21 +111,76 @@ const session = await composio.create("user_123", {
111
</Step>
112
</Steps>
113
131
-You can mix and match: use your own OAuth app for toolkits where branding matters (GitHub, Google) and Composio managed auth for everything else.
114
+## Using both together
115
133
-## Common patterns
116
+Most production apps mix both. Use your own credentials for toolkits where users see consent screens (GitHub, Google, Slack) and let Composio managed auth handle the rest.
117
135
-### Development to production
118
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
119
+<Tab value="Python">
120
+```python
121
+session = composio.create(
122
+ user_id="user_123",
123
+ auth_configs={
124
+ "github": "ac_your_github_config",
125
+ "google": "ac_your_google_config",
126
+ # everything else uses Composio managed auth automatically
127
+ },
128
+)
129
+```
130
+</Tab>
131
+<Tab value="TypeScript">
132
+```typescript
133
+import { Composio } from '@composio/core';
134
+const composio = new Composio();
135
+// ---cut---
136
+const session = await composio.create("user_123", {
137
+ authConfigs: {
138
+ github: "ac_your_github_config",
139
+ google: "ac_your_google_config",
140
+ // everything else uses Composio managed auth automatically
141
+ },
142
+});
143
+```
144
+</Tab>
145
+</Tabs>
146
+
147
+### Moving from managed to custom
148
137
-Start with Composio managed apps during development. When you're ready for production, register your own OAuth apps for user-facing toolkits and pass them as auth configs. No code changes needed beyond adding the `auth_configs` parameter.
149
+Start with managed apps during development. When you're ready for production, register your own OAuth apps for the toolkits that matter and add the `auth_configs` parameter. No other code changes needed.
150
+
151
+Existing connected accounts keep working because they stay tied to the auth config they were created with. New connections go through your own credentials. See [Switching from managed to custom](/docs/white-labeling-authentication#switching-from-composio-managed-to-your-own-oauth-app) for details.
152
153
### Toolkits without managed auth
154
141
-Some toolkits (PostHog, Tavily, Perplexity, etc.) don't have Composio managed auth. For these, you must create a custom auth config with your own credentials. See [Using custom auth configuration](/docs/using-custom-auth-configuration) for a step-by-step walkthrough.
155
+Some toolkits (PostHog, Tavily, Perplexity, etc.) don't have Composio managed auth. For these, you must create a custom auth config with your own credentials. See [Using custom auth configuration](/docs/using-custom-auth-configuration).
156
+
157
+## FAQ
158
+
159
+<Accordions>
160
+<Accordion title="Can I use managed auth for some toolkits and custom apps for others?">
161
+Yes. Pass `auth_configs` only for the toolkits where you want your own credentials. Everything else automatically uses Composio managed auth. This is the most common pattern in production.
162
+</Accordion>
163
+
164
+<Accordion title="Will switching to a custom app break existing connected accounts?">
165
+No. Existing connected accounts are tied to the auth config they were created with and keep working. Only new connections go through your custom OAuth app. To fully migrate existing users, delete their old connected accounts and have them re-authenticate. See [Switching from managed to custom](/docs/white-labeling-authentication#switching-from-composio-managed-to-your-own-oauth-app).
166
+</Accordion>
167
+
168
+<Accordion title="Do I need a custom app for API key-based toolkits?">
169
+No. API key-based toolkits (like Tavily, Perplexity) don't have OAuth consent screens, so there's no branding to customize. You still need to create a custom auth config to provide your API key, but you don't need to register an OAuth app.
170
+</Accordion>
171
+
172
+<Accordion title="Does Composio still handle token refresh with custom apps?">
173
+Yes. Composio manages token refresh regardless of whether you use managed or custom OAuth credentials. You don't need to handle re-authentication or token expiration.
174
+</Accordion>
175
143
-### White-labeling
176
+<Accordion title="What happens if Composio's managed OAuth app hits rate limits?">
177
+Managed apps share quota across all Composio users. If you're seeing rate limit errors, switching to your own OAuth app gives you a dedicated quota. This is one of the main reasons to use your own app in production.
178
+</Accordion>
179
145
-If you need full branding control (consent screens, Connect Link page, and redirect URLs), see the [White-labeling authentication](/docs/white-labeling-authentication) guide.
180
+<Accordion title="Can I create custom auth configs programmatically?">
181
+Yes. Use the SDK instead of the dashboard. See [Programmatic auth configs](/docs/auth-configuration/programmatic-auth-configs) for examples.
182
+</Accordion>
183
+</Accordions>
184
185
## What to read next
186