@devries-cameron20 / composio-1 / commits / d3baef00e
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: apply review suggestions to managed vs custom auth and the move guide

Wording: managed apps work in production, the shared OAuth app is why you may hit shared provider rate limits, and your own app is a recommendation. Rename "What a managed app limits" to "What changes with your own app", drop the 2-minute polling bullet, retitle the guide "Move to your own OAuth app" and update its links, and link the rate-limits guide (needs #5323). Leaves out "per-plan usage limits", which are not enforced yet. Trigger migration fixes: - copy each trigger's delivery type and polling interval, leaving a fallback to polling for Composio to decide again - keep a map of old to new trigger IDs and update event filters, webhook handlers and stored links before disabling the old triggers - revoke the upstream token before deleting the managed connected account Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Jeevesh Jain committed Nov 12, 2026 at 23:05 UTC d3baef00e62804faeb8028563c38678c6f12f93c
4 files changed +53 -27
docs/content/docs/authentication/custom-app-vs-managed-app.mdx
+9 -9
@@ -9,7 +9,7 @@ Composio supports two ways to authenticate users with toolkits.
9 - **[Composio-managed apps](/toolkits/managed-auth)**: Composio registers and maintains OAuth apps for popular toolkits such as GitHub, Gmail, and Slack. You don't register an OAuth app.
10 - **Custom auth configs**: You provide your own OAuth app, API key, bearer token, or other credentials and tell Composio to use them for a toolkit.
11
12 -A Composio-managed app works in production, but it isn't built for production scale. Move to your own app before you scale.
12 +A Composio-managed app works in production. Its OAuth app is shared with other Composio customers, so you may run into shared provider rate limits as your usage grows. When you're ready for higher volume, we recommend your own OAuth app.
13
14 Both options use Composio to store and refresh connected-account credentials. Choosing your own OAuth app changes app ownership, branding, scopes, and provider quota, not [token custody](/docs/security/token-custody#oauth-app-ownership-and-token-custody).
15
@@ -20,16 +20,15 @@ Both options use Composio to store and refresh connected-account credentials. Ch
20
21 You can still [white-label the Connect Link page](/docs/authentication/white-labeling-authentication#customizing-the-connect-link) with your logo and app title on a managed app.
22
23 -## What a managed app limits
23 +## What changes with your own app
24
25 -- **Shared provider quota.** Provider quotas that apply per OAuth app are shared by every Composio customer on the managed app, so traffic you don't control counts against the limit your users depend on. Your own app gets its own quota. See [provider quota errors](/reference/rate-limits#provider-quota-errors).
26 -- **Composio's name on the consent screen.** Users see Composio's app name when they approve access, not yours.
27 -- **Composio's scope set.** You can [adjust scopes](/docs/authentication/controlling-scopes) on a managed config, but only within what Composio's app is set up to request. A scope outside that set needs your own app.
28 -- **Slower polling triggers.** Managed auth enforces a 2-minute minimum polling interval. Your own app can use shorter intervals where supported.
25 +- **Dedicated provider rate limits.** Some provider limits apply per OAuth app. On a managed app, connections share them with other Composio customers. Your own app has its own. See [Avoid and recover from rate limits](/docs/poc-to-prod/avoid-rate-limits) and [provider quota errors](/reference/rate-limits#provider-quota-errors).
26 +- **Your name on the consent screen.** Users see your app name when they approve access.
27 +- **Your own scopes.** You can [adjust scopes](/docs/authentication/controlling-scopes) on a managed config, but only within what Composio's app is set up to request. A scope outside that set needs your own app.
28
30 -## When to move to your own app
29 +## When your own app makes sense
30
32 -Move before you scale. Switching later means existing users reconnect, so the cost grows with your user count. Also move when any of these apply:
31 +If you expect high volume, we suggest setting up your own app early. Managed connections keep working until you move them, and users reconnect once when you do, so an earlier move means fewer people to reconnect. Your own app also makes sense when any of these apply:
32
33 - **You need your app name on OAuth consent screens.** Your product or your enterprise customers require your branding end to end.
34 - **You need custom scopes.** Composio's scopes may not include everything you need, for example write access to a specific Google API.
@@ -39,7 +38,7 @@ Move before you scale. Switching later means existing users reconnect, so the co
38
39 Some toolkits have no managed app at all. See [Toolkits without managed auth](#toolkits-without-managed-auth).
40
42 -Already have users on a managed app? Follow [Move from a Composio-managed app to your own OAuth app](/docs/migration-guide/managed-to-own-app) to switch while existing connections keep working.
41 +Ready to move? Follow [Move to your own OAuth app](/docs/migration-guide/managed-to-own-app). Existing connections keep working while you switch.
42
43 ## Create a custom auth config
44
@@ -175,4 +174,5 @@ Some OAuth toolkits do not have a Composio-managed OAuth app. Check [Managed OAu
174 <Cards>
175 <Card icon={<Code />} title="Programmatic auth configs" href="/docs/authentication/programmatic-auth-configs" description="Create auth configs in code and pass them to a session" />
176 <Card icon={<RouteIcon />} title="Move to your own OAuth app" href="/docs/migration-guide/managed-to-own-app" description="Switch existing users from a Composio-managed app to your own" />
177 + <Card icon={<Zap />} title="Avoid and recover from rate limits" href="/docs/poc-to-prod/avoid-rate-limits" description="Spot which limit you hit, retry well, and shape traffic" />
178 </Cards>
docs/content/docs/authentication/white-labeling-authentication.mdx
+1 -1
@@ -242,7 +242,7 @@ Set `COMPOSIO_API_KEY` in your server environment. Persist `request.id` with the
242 ### Switching from Composio-managed to your own OAuth app
243
244 Existing connected accounts stay on the auth config they were created with, and tokens issued to Composio's app can't move to yours, so existing users reconnect.
245 -Follow [Move from a Composio-managed app to your own OAuth app](/docs/migration-guide/managed-to-own-app) to run both configs side by side, reconnect users, and recreate their triggers.
245 +Follow [Move to your own OAuth app](/docs/migration-guide/managed-to-own-app) to run both configs side by side, reconnect users, and recreate their triggers.
246
247 ## Build an app-owned connection UI
248
docs/content/docs/migration-guide/index.mdx
+2 -2
@@ -13,8 +13,8 @@ written: "December 2025"
13 [View No Auth to Instant migration guide →](/docs/migration-guide/no-auth-to-instant)
14 </Accordion>
15
16 - <Accordion title="Move from a Composio-managed app to your own OAuth app">
17 - Switch a toolkit to your own OAuth app. New users connect to your app, and existing users keep working on the managed app until they reconnect.
16 + <Accordion title="Move to your own OAuth app">
17 + Move a toolkit to your own OAuth app when you're ready. New users connect to your app, and existing users keep working on the managed app until they reconnect.
18
19 [View managed app migration guide →](/docs/migration-guide/managed-to-own-app)
20 </Accordion>
docs/content/docs/migration-guide/managed-to-own-app.mdx
+41 -15
@@ -1,10 +1,10 @@
1 ---
2 -title: Move from a Composio-managed app to your own OAuth app
2 +title: Move to your own OAuth app
3 description: Register your own OAuth app, route new connections to it, reconnect existing users, and recreate their triggers
4 keywords: [migrate, managed auth, own oauth app, custom auth config, bring your own app, reconnect, white label, provider quota]
5 ---
6
7 -This guide is for apps that already have users connected through a [Composio-managed app](/toolkits/managed-auth) and want to switch a toolkit to their own OAuth app. To decide whether you need to, read [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app).
7 +Use this guide when you're ready to move a toolkit to your own OAuth app, for example for dedicated rate limits or your own name on the consent screen. Managed connections keep working while you switch, so you can move on your own schedule. To decide whether to move, read [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) and [Avoid and recover from rate limits](/docs/poc-to-prod/avoid-rate-limits).
8
9 You move one toolkit at a time. Each toolkit gets its own auth config, so Gmail can move while Slack stays on the managed app.
10
@@ -213,7 +213,7 @@ Use the same user ID the managed connection has. A different user ID creates a c
213 <Step>
214 <StepTitle>Recreate triggers on the new connection</StepTitle>
215
216 -Triggers stay attached to the managed connected account. List them, create the same trigger type and config on the new connected account, then disable the old instance:
216 +Triggers stay attached to the managed connected account. List them and create each one on the new connected account with the same trigger config, delivery type, and polling interval. Keep a map from each old trigger ID to its new one:
217
218 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
219 <Tab value="Python">
@@ -226,13 +226,21 @@ old_triggers = composio.triggers.list_active(
226 connected_account_ids=["ca_old_managed_account"],
227 )
228
229 +new_trigger_ids = {}
230 for trigger in old_triggers.items:
230 - composio.triggers.create(
231 + new_trigger = composio.triggers.create(
232 slug=trigger.trigger_name,
233 connected_account_id="ca_new_own_app_account",
234 trigger_config=trigger.trigger_config,
235 + # A fallback to polling is left for Composio to decide again
236 + type=None if trigger.fallback_reason else trigger.type,
237 + polling_interval=trigger.polling_interval,
238 )
235 - composio.triggers.disable(trigger_id=trigger.id)
239 + new_trigger_ids[trigger.id] = new_trigger.trigger_id
240 +
241 +# After your event filters use the new IDs, disable the old instances
242 +for old_trigger_id in new_trigger_ids:
243 + composio.triggers.disable(trigger_id=old_trigger_id)
244 ```
245 </Tab>
246 <Tab value="TypeScript">
@@ -245,12 +253,21 @@ const oldTriggers = await composio.triggers.listActive({
253 connectedAccountIds: ['ca_old_managed_account'],
254 });
255
256 +const newTriggerIds = new Map<string, string>();
257 for (const trigger of oldTriggers.items) {
249 - await composio.triggers.create('user_123', trigger.triggerName, {
258 + const newTrigger = await composio.triggers.create('user_123', trigger.triggerName, {
259 connectedAccountId: 'ca_new_own_app_account',
260 triggerConfig: trigger.triggerConfig,
261 + // A fallback to polling is left for Composio to decide again
262 + type: trigger.fallbackReason ? undefined : trigger.type,
263 + pollingInterval: trigger.pollingInterval ?? undefined,
264 });
253 - await composio.triggers.disable(trigger.id);
265 + newTriggerIds.set(trigger.id, newTrigger.triggerId);
266 +}
267 +
268 +// After your event filters use the new IDs, disable the old instances
269 +for (const oldTriggerId of newTriggerIds.keys()) {
270 + await composio.triggers.disable(oldTriggerId);
271 }
272 ```
273 </Tab>
@@ -258,16 +275,18 @@ for (const trigger of oldTriggers.items) {
275 ```bash
276 # List triggers on the managed connection
277 curl -s "https://backend.composio.dev/api/v3.1/trigger_instances/active?connected_account_ids=ca_old_managed_account" \
261 - -H "x-api-key: $COMPOSIO_API_KEY" | jq '.items[] | {id, trigger_name, trigger_config}'
278 + -H "x-api-key: $COMPOSIO_API_KEY" | jq '.items[] | {id, trigger_name, trigger_config, type, fallback_reason, polling_interval}'
279
280 # For each one, create the same trigger type on the new connection.
264 -# Use its trigger_name in the URL and copy its trigger_config into the body.
281 +# Use its trigger_name in the URL. Copy its trigger_config and polling_interval,
282 +# and its type unless fallback_reason is set. Save the returned trigger_id.
283 curl -X POST https://backend.composio.dev/api/v3.1/trigger_instances/GMAIL_NEW_GMAIL_MESSAGE/upsert \
284 -H "x-api-key: $COMPOSIO_API_KEY" \
285 -H "Content-Type: application/json" \
268 - -d '{"user_id": "user_123", "connected_account_id": "ca_new_own_app_account", "trigger_config": {}}'
286 + -d '{"user_id": "user_123", "connected_account_id": "ca_new_own_app_account", "trigger_config": {}, "type": "poll", "polling_interval": 15}' \
287 + | jq '{trigger_id, type, polling_interval}'
288
270 -# Then disable the old instance
289 +# After your event filters use the new trigger_id, disable the old instance
290 curl -X PATCH https://backend.composio.dev/api/v3.1/trigger_instances/manage/ti_old_trigger \
291 -H "x-api-key: $COMPOSIO_API_KEY" \
292 -H "Content-Type: application/json" \
@@ -276,7 +295,9 @@ curl -X PATCH https://backend.composio.dev/api/v3.1/trigger_instances/manage/ti_
295 </Tab>
296 </Tabs>
297
279 -Results are cursor-paginated. If the list returns a next cursor, fetch the next page as shown in [Listing active triggers](/docs/setting-up-triggers/managing-triggers#listing-active-triggers). Polling triggers on your own app can use shorter intervals than the managed minimum where the toolkit supports it.
298 +Results are cursor-paginated. If the list returns a next cursor, fetch the next page as shown in [Listing active triggers](/docs/setting-up-triggers/managing-triggers#listing-active-triggers).
299 +
300 +Events from the new triggers carry the new trigger ID and connected account ID. Before you disable the old instances, update anything that matches on the old values: [event subscriptions filtered by trigger ID](/docs/setting-up-triggers/subscribing-to-events), webhook handlers, and any stored links between a user and their trigger or connected account.
301
302 Disable the old trigger rather than deleting it until you've confirmed events arrive from the new one. Otherwise both instances fire for the same event while they overlap.
303 </Step>
@@ -284,9 +305,13 @@ Disable the old trigger rather than deleting it until you've confirmed events ar
305 <Step>
306 <StepTitle>Retire the managed connections</StepTitle>
307
287 -After a user's new connection works, [disable](/docs/auth-configuration/connected-accounts#enable-and-disable-accounts) their managed connected account. Disabling an account also disables its triggers, and you can re-enable it if something goes wrong. Once you're confident, [delete the old triggers](/docs/setting-up-triggers/managing-triggers#deleting-triggers) and [delete the managed connected account](/docs/auth-configuration/connected-accounts#delete-accounts). Deletion is permanent.
308 +After a user's new connection works, [disable](/docs/auth-configuration/connected-accounts#enable-and-disable-accounts) their managed connected account. Disabling an account also disables its triggers, and you can re-enable it if something goes wrong.
309 +
310 +Once you're confident, clean up in this order:
311
289 -To revoke the upstream token as well, use [Revoke accounts](/docs/auth-configuration/connected-accounts#revoke-accounts) where the toolkit supports it.
312 +1. Optionally, [revoke the upstream token](/docs/auth-configuration/connected-accounts#revoke-accounts) where the toolkit supports it. Revoking needs the connected account to still exist, so do it before you delete.
313 +2. [Delete the old triggers](/docs/setting-up-triggers/managing-triggers#deleting-triggers).
314 +3. [Delete the managed connected account](/docs/auth-configuration/connected-accounts#delete-accounts). This removes it from Composio and is permanent.
315
316 When no active connections remain on the managed config, every user is on your app. You can then pass your config in every session and drop the routing logic.
317 </Step>
@@ -305,6 +330,7 @@ When no active connections remain on the managed config, every user is on your a
330 ## Next
331
332 <Cards>
308 - <Card icon={<Key />} title="Managed vs custom auth" href="/docs/authentication/custom-app-vs-managed-app" description="What a managed app limits and when to move" />
333 + <Card icon={<Key />} title="Managed vs custom auth" href="/docs/authentication/custom-app-vs-managed-app" description="What changes with your own app and when it makes sense" />
334 + <Card icon={<Zap />} title="Avoid and recover from rate limits" href="/docs/poc-to-prod/avoid-rate-limits" description="Spot which limit you hit, retry well, and shape traffic" />
335 <Card icon={<Palette />} title="White-labeling authentication" href="/docs/authentication/white-labeling-authentication" description="Brand the Connect Link and configure callback URLs" />
336 </Cards>