@devries-cameron20 / composio-1 / commits / b8b23c1e8
Fork 0

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: add custom app vs managed app guide

Explains when to use your own OAuth app credentials vs Composio's managed authentication, with comparison table and code examples. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmitha Mallesh committed Mar 9, 2026 at 18:39 UTC b8b23c1e8df26458f13751d6a2aff057b19d9f94
2 files changed +154
docs/content/docs/custom-app-vs-managed-app.mdx new
+153
@@ -0,0 +1,153 @@
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]
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.
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.
10 +
11 +## Quick decision
12 +
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
18 +
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:
42 +
43 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
44 +<Tab value="Python">
45 +```python
46 +from composio import Composio
47 +
48 +composio = Composio()
49 +session = composio.create(user_id="user_123")
50 +# GitHub, Gmail, Slack, etc. all use Composio managed auth by default
51 +```
52 +</Tab>
53 +<Tab value="TypeScript">
54 +```typescript
55 +import { Composio } from '@composio/core';
56 +
57 +const composio = new Composio();
58 +const session = await composio.create("user_123");
59 +// GitHub, Gmail, Slack, etc. all use Composio managed auth by default
60 +```
61 +</Tab>
62 +</Tabs>
63 +
64 +When a user needs to connect, the OAuth consent screen will show "Composio" as the requesting application.
65 +
66 +## How to use your own custom app
67 +
68 +<Steps>
69 +<Step>
70 +<StepTitle>Register an OAuth app with the toolkit</StepTitle>
71 +
72 +Go to the toolkit's developer portal (e.g., [GitHub](https://github.com/settings/developers), [Google Cloud Console](https://console.cloud.google.com/)) and create a new OAuth app. Set the callback URL to:
73 +
74 +```
75 +https://backend.composio.dev/api/v3/toolkits/auth/callback
76 +```
77 +
78 +Copy your **Client ID** and **Client Secret**.
79 +</Step>
80 +
81 +<Step>
82 +<StepTitle>Create a custom auth config in Composio</StepTitle>
83 +
84 +In the [Composio dashboard](https://platform.composio.dev):
85 +
86 +1. Go to **Authentication management** and click **Create Auth Config**
87 +2. Select the toolkit (e.g., GitHub)
88 +3. Choose the **OAuth2** scheme
89 +4. Toggle on **Use your own developer credentials**
90 +5. Enter your **Client ID** and **Client Secret**
91 +6. Click **Create**
92 +
93 +Copy the auth config ID (e.g., `ac_1234abcd`).
94 +</Step>
95 +
96 +<Step>
97 +<StepTitle>Pass the auth config ID in your session</StepTitle>
98 +
99 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
100 +<Tab value="Python">
101 +```python
102 +from composio import Composio
103 +
104 +composio = Composio()
105 +session = composio.create(
106 + user_id="user_123",
107 + auth_configs={
108 + "github": "ac_your_github_config",
109 + # toolkits not listed here still use Composio managed auth
110 + },
111 +)
112 +```
113 +</Tab>
114 +<Tab value="TypeScript">
115 +```typescript
116 +import { Composio } from '@composio/core';
117 +
118 +const composio = new Composio();
119 +const session = await composio.create("user_123", {
120 + authConfigs: {
121 + github: "ac_your_github_config",
122 + // toolkits not listed here still use Composio managed auth
123 + },
124 +});
125 +```
126 +</Tab>
127 +</Tabs>
128 +</Step>
129 +</Steps>
130 +
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.
132 +
133 +## Common patterns
134 +
135 +### Development to production
136 +
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.
138 +
139 +### Toolkits without managed auth
140 +
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.
142 +
143 +### White-labeling
144 +
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.
146 +
147 +## What to read next
148 +
149 +<Cards>
150 + <Card icon={<Key />} title="Custom auth configs" href="/docs/auth-configuration/custom-auth-configs" description="Detailed setup for custom OAuth apps, API keys, and other auth types" />
151 + <Card icon={<Palette />} title="White-labeling authentication" href="/docs/white-labeling-authentication" description="Remove all Composio branding from your auth flows" />
152 + <Card icon={<Wrench />} title="Programmatic auth configs" href="/docs/auth-configuration/programmatic-auth-configs" description="Create and manage auth configs via the SDK" />
153 +</Cards>
docs/content/docs/meta.json
+1
@@ -24,6 +24,7 @@
24 "using-custom-auth-configuration",
25 "webhook-verification",
26 "subscribing-to-connection-expiry-events",
27 + "custom-app-vs-managed-app",
28 "native-tools-vs-mcp",
29 "sessions-vs-direct-execution",
30 "---Features---",