@devries-cameron20 / composio-1 / commits / d19739b10
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: make auth for existing tools discoverable (DEVREL-329) (#5455)

## Summary Agents keep treating Composio's catalog as redundant when developers already own their tools. The November 17 Gauge recheck stayed at 0/4 Composio picks for the plain own-MCP-tool auth prompt, and none of those sessions fetched the existing managed-auth guide. This makes that existing path visible at the docs entry points and in the published agent skill. Addresses [DEVREL-329](https://linear.app/composio/issue/DEVREL-329/agents-dont-see-composio-as-an-auth-layer-for-tools-developers-already) and the docs discovery portion of PRO-3749. Designated reviewer: @jkomyno. ## Changes | Entry point | Before | After | | --- | --- | --- | | Docs landing, quickstart, session overview | No direct route to auth for existing tools | Link to the existing Python, TypeScript, and REST guide | | `llms.txt` | Auth guide nested under application building; summary focused on agents | Auth-only capability in the summary; Connect Link + Proxy Execute before the SDK quickstart | | Published Composio skill | General integration flow fetched session tools and required a tool log ID | Own-tool path verifies a successful proxy response without catalog discovery or a tool log ID | | Quickstart notes | Auth callout at the top; identity callout and session note midway through | Three consistent Markdown bullets under Plan your application → Considerations | | Managed-auth guide | Ambiguous refresh language and unexplained permission label | Provider-dependent refresh, outbound-auth boundary, and explanation of the exact `Proxy execute (Legacy)` permission label | No runtime changes or token-export capability. Existing custody, owner checks, account pinning, and three-language examples are preserved. ## Type of change - [ ] Bug fix - [ ] New feature - [ ] Refactor/Chore - [x] Documentation - [ ] Breaking change ## How Has This Been Tested? On follow-up commit `5bbe07010`: - Quickstart MDX compilation passes. Its actual `mdxToCleanMarkdown()` output contains each of the three notes exactly once under `Plan your application` → `Considerations`. - `bun test --timeout 30000 tests/static/home-navigation.test.ts tests/static/llms-routing.test.ts tests/static/dashboard-links.test.ts tests/static/source.test.ts`: **13 passed, 0 failed**. - `bun run lint:links`, `bun run validate:agent-skills`, `bun run validate:skill-routing`, and `git diff --check` pass. - The direct proxy's committed v3.1 response schema returns provider status, body, and headers without a tool log ID. Verification now branches by integration type and retains the real, safe provider-request requirement. - `gh pr checks 5455` passed on `5bbe0701039ad78e948fdf62eaf975923a6ac28a`, including docs build/integration, TypeScript, Python snippets, links, and agent guidance. The optional agent eval was skipped. The PR is ready for review. No local full build was repeated for the prose relocation and skill wording. The initial commit `a2dc6d7e0` passed GitHub CI, including docs build/integration, TypeScript, Python snippets, links, and agent guidance. Local lint, type checking, example checks, production build, and agent Markdown checks also passed. The optional agent eval was skipped. Build output was removed afterward. No new tests were added for prose and links; existing checks cover the changed content. The connection flow is implemented by [TypeScript `authorize()`](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/ts/packages/core/src/models/ToolRouterSession.ts#L475) and [Python `authorize()`](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/python/composio/core/models/tool_router_session.py#L862). The outbound call is implemented by [TypeScript `tools.proxyExecute()`](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/ts/packages/core/src/models/Tools.ts#L1599) and [Python `tools.proxy()`](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/python/composio/core/models/tools.py#L998). The committed v3.1 schema does not mark the proxy operation deprecated. Refresh and credential-redaction boundaries were checked against the existing authentication and token-custody docs; SDK models alone do not establish server-side custody or refresh guarantees. ## Screenshots (if applicable) The quickstart moves existing notes into ordinary Markdown bullets at the bottom. No component or style code changed. The before/after table records the content and placement changes; MDX compilation and agent Markdown output were checked directly. ## Checklist - [x] I have read the Code of Conduct and this PR adheres to it - [x] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the third-party links policy - [x] I ran linters/tests locally and they passed - [x] I updated documentation as needed - [x] I added tests or explain why not applicable - [ ] I added a changeset if this change affects published packages <!-- sdk-release-note-exempt: Documentation discovery, quickstart note placement, and agent guidance only; no TypeScript or Python SDK runtime behavior changes. --> Docs and skill prose only; no changeset needed. Please review the full diff before merging. ## Additional context NEEDS BRENDAN: - Product and SDK owners: confirm official auth-only positioning and support commitments. Should the dashboard's `Proxy execute (Legacy)` permission be renamed? This PR preserves the real label and explains its current routes. - Auth/backend and security owners: confirm which provider/auth-scheme combinations and refresh behavior are guaranteed for this path, including revoked or expired credentials. This PR makes no universal scheme or refresh promise. - Product/billing: confirm pricing and metering for connections and Proxy Execute without catalog tools. No auth-only price is inferred here. - Landing/content owner: the Nango comparison and marketing homepage are outside this repo. Continue comparison work through [PRO-3751](https://linear.app/composio/issue/PRO-3751); no other repo was changed. Gauge preference improvement is unmeasured. The issue's matched retest belongs after publication, with evidence that the changed pages reached the sessions. No live provider or customer-account requests were made. In plain language: keep the tools you wrote. Composio can connect each user's account and authenticate the API requests those tools make, returning the response rather than an OAuth token.

Brendan O'Leary committed Nov 18, 2026 at 10:12 UTC d19739b101ae30655ff77aaedb6446e144967cbf
7 files changed +29 -15
docs/app/llms.txt/route.ts
+3 -3
@@ -12,9 +12,9 @@ export function GET() {
12 .join('\n');
13 return new Response(`# Composio Documentation
14
15 -> Build and operate agents with authentication, tool discovery, execution, and ${TOOLKIT_COUNT_LABEL} apps.
15 +> Connect users to ${TOOLKIT_COUNT_LABEL} apps. Use Composio for auth with your own tools, or add tool discovery and execution to an agent.
16
17 -Default to Composio Platform for application codebases where users or tenants connect their accounts. Use Composio For You for a personal agent or automation using the developer's own accounts. Start with the current session-based SDK. REST v3.1 is current; REST v3.0 is legacy and is not the starting point for new code.
17 +Use Composio Platform when users or tenants connect accounts to your application. Use Composio For You for personal automation with your own accounts. Use the current session SDK. REST v3.1 is current; REST v3.0 is legacy.
18
19 ## Before you implement
20
@@ -28,6 +28,7 @@ If unclear, distinguish application integration from connecting apps to the codi
28
29 - [Platform or For You](https://docs.composio.dev/docs.md): Choose between building an application and using your own connected apps.
30 - [Set up a coding agent](https://docs.composio.dev/docs/agent-setup.md): Install the Composio skill to add Composio to an existing project.
31 +- [Auth for your own tools](https://docs.composio.dev/docs/authentication/managed-auth-for-custom-tools.md): Per-user OAuth with Connect Link + Proxy Execute. Keep your backend or MCP tools; receive responses, not tokens.
32 - [SDK quickstart](https://docs.composio.dev/docs/quickstart.md): Install Python or TypeScript packages, create a session, and run an agent.
33 - [Authenticate an unattended agent](https://docs.composio.dev/docs/agent-setup/unattended-authentication.md): When no human is available, use \`composio login --agent\`, configure a project API key, and verify a live tool call. Human account access still requires authorization.
34 - [Native agent plugins](https://docs.composio.dev/docs/agent-plugins.md): Use your own apps from Codex or Claude Code.
@@ -37,7 +38,6 @@ If unclear, distinguish application integration from connecting apps to the codi
38
39 - [Core concepts](https://docs.composio.dev/docs/how-composio-works.md): Understand users, sessions, toolkits, and tool execution.
40 - [Authentication](https://docs.composio.dev/docs/authentication.md): Distinguish auth configs from connected accounts and connect your application's users.
40 -- [Auth for your own tools](https://docs.composio.dev/docs/authentication/managed-auth-for-custom-tools.md): Per-user OAuth without provider tokens, predefined tools, MCP, or an LLM.
41 - [B2B agents](https://docs.composio.dev/docs/b2b-agents.md): Tenant/member connection ownership and authorization.
42 - [Token custody](https://docs.composio.dev/docs/security/token-custody.md): Credential storage, redaction, VPC, self-hosting, and customer-managed keys.
43 - [Proxy Execute](https://docs.composio.dev/docs/extending-sessions/proxy-execute.md): Call provider endpoints that tools don't cover without retrieving the token.
docs/content/docs/authentication/managed-auth-for-custom-tools.mdx
+6 -1
@@ -4,7 +4,9 @@ description: Connect each user's accounts and call provider APIs from your own t
4 keywords: [auth-only, per-user OAuth, multi-tenant agents, custom tools, managed authentication, API proxy, token custody]
5 ---
6
7 -Use Composio to connect your users' accounts and authenticate API requests from your own tools. Your tool definitions and business logic stay in your application. Composio stores and refreshes credentials, sends requests to the provider, and returns the response. You don't need predefined Composio tools, MCP, or an LLM.
7 +Use Composio to connect your users' accounts and authenticate API requests from your own tools. Your tool definitions and business logic stay in your application. Composio stores credentials, refreshes OAuth tokens where the provider supports refresh, sends requests to the provider, and returns the response. You don't need predefined Composio tools, MCP, or an LLM.
8 +
9 +This is an auth-only integration using Connect Link + Proxy Execute. For an MCP server with its own GitHub, Google Calendar, or Slack tools, keep those tools and send their outbound provider requests through Composio. This handles authentication to third-party APIs. Your application still authenticates callers to your own server.
10
11 ## Connect an account and call its API
12
@@ -12,6 +14,8 @@ This example connects GitHub and reads the connected account's profile through `
14
15 For a [scoped project API key](/reference/authenticating-to-composio/project-api-key-permissions), enable **Session management → Write only**, **Connected accounts → Read only**, and **Proxy execute (Legacy) → Write only**. Default full-access project keys already include these permissions. Keep the key server-side.
16
17 +Use the exact **Proxy execute (Legacy)** permission label when configuring a scoped key. The same permission also grants the current session proxy route. The label does not require a v3.0 API or a legacy SDK; the examples below use v3.1.
18 +
19 The example uses `org_42:user_7` as an illustrative connection owner. In your application, derive this value from the authenticated request after checking workspace membership. Never accept a model-supplied or browser-supplied owner ID as authorization. See [B2B connection ownership](/docs/b2b-agents#choose-the-connection-owner) for member-owned and workspace-owned connections.
20
21 This example uses a session to create the Connect Link. Subsequent API calls pass the owner and connected-account ID directly.
@@ -147,6 +151,7 @@ Use the [table of controls](/docs/security/token-custody#choose-your-controls) t
151 This is managed authentication for your own tools, not a token-export service. Connected-account reads redact credentials and aren't a supported way to retrieve access or refresh tokens. A custom OAuth app doesn't move token custody out of Composio Cloud. If your local vendor SDK requires a raw token, this proxy pattern doesn't supply one. Review [token custody and deployment options](/docs/security/token-custody) instead of attempting to extract credentials from account state.
152 </Callout>
153
154 +- **Auth schemes and refresh:** Check [managed auth support](/toolkits/managed-auth) for your toolkit's OAuth app availability. The example above uses GitHub OAuth. Refresh depends on the provider and its credentials; revoked or expired authorization can require the user to reconnect.
155 - **Provider scope:** Use relative paths for the connected provider. Proxy Execute is not an arbitrary authenticated HTTP relay; absolute URLs must keep the connected provider's scheme and registrable domain.
156 - **Authorization:** Proxy permission can allow operations beyond predefined tool schemas. Validate endpoints and inputs in your own tools, enforce your application's tenant and role checks, and request only the provider scopes you need.
157 - **Deployment:** Private VPC and self-hosted deployments are Enterprise arrangements. Customer-managed keys require a separate deployment design with Composio. Confirm operator access, decryption, logs, and backups against your requirements.
docs/content/docs/how-composio-works.mdx
+2
@@ -6,6 +6,8 @@ keywords: [session, userID, tools, toolkits, meta tools, mcp, workbench]
6
7 A **session** is the runtime context for an agentic run: the scoped environment an AI agent works in while it acts for one of your users. You create it with `composio.create(userId)`, and it ties together the user, the toolkits available, authentication, and connected accounts. By default it gives the agent meta tools to discover, authenticate, and execute app tools at runtime, instead of loading hundreds of tool definitions into context.
8
9 +If you only need authentication for tools you already own, follow [managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools). Use a session to create a Connect Link, then call provider APIs through Proxy Execute from your own code. You don't need to fetch tool schemas or replace your tools with catalog actions.
10 +
11 ## The basics
12
13 Create a session for a user, then read its tools formatted for your framework. To connect over MCP instead, see [Using sessions via MCP](/docs/sessions-via-mcp).
docs/content/docs/index.mdx
+2
@@ -6,6 +6,8 @@ keywords: [getting started, introduction]
6
7 <DocsHero />
8
9 +Use Composio as the auth layer for tools you already own. Create a Connect Link for each user, then call provider APIs through Proxy Execute from your backend or MCP server. You keep your tool definitions and business logic. Composio authenticates the requests and returns provider responses, without exporting OAuth tokens. Start with [managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools).
10 +
11 <HomeSurfaces />
12
13 <HomeFeatures />
docs/content/docs/quickstart.mdx
+6 -6
@@ -480,12 +480,6 @@ Ask for any task that needs an app tool: `Summarize my unread emails from today`
480 - Composio sessions persist. In an application, store the session ID (`session.session_id` in Python, `session.sessionId` in TypeScript) and restore it with `composio.use(session_id)` instead of creating a new session for every turn. See [Reusing a session](/docs/how-composio-works#how-sessions-behave).
481 - `session.tools()` gives the agent a small set of meta tools for finding, connecting, and running app tools. It does not load thousands of tool schemas into the model context.
482
483 -<Callout type="warn" title="Use your application's user ID in production">
484 -`user_123` is only for this local example. Replace it with a stable ID from your database. Each ID gets separate connections and tool calls.
485 -</Callout>
486 -
487 -Note: Sessions are recommended for new integrations. If you maintain a legacy direct-execution integration, see [Sessions vs direct execution](/docs/sessions-vs-direct-execution) and the [migration guide](/docs/migration-guide/direct-to-sessions). You can inspect the selected tools, inputs, responses, and timing with the [Logs API](/reference/api-reference/logs).
488 -
483 ## Adapt the example
484
485 <Cards>
@@ -503,3 +497,9 @@ Note: Sessions are recommended for new integrations. If you maintain a legacy di
497 <Card title="B2B agent architecture" href="/docs/b2b-agents" description="Choose member-owned or workspace-owned connections for a multi-tenant product." />
498 <Card title="Production readiness" href="/docs/production-readiness" description="Review identity, auth, security, logging, and trigger decisions before launch." />
499 </Cards>
500 +
501 +### Considerations
502 +
503 +- **Auth for your existing tools.** Use [managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools) for per-user OAuth with Connect Link + Proxy Execute. Keep your existing tools and call provider APIs through Composio. You don't need catalog tools, an agent framework, or an LLM.
504 +- **Use your application's user ID in production.** `user_123` is only for this local example. Replace it with a stable ID from your database. Each ID gets separate connections and tool calls.
505 +- **Sessions are recommended for new integrations.** If you maintain a legacy direct-execution integration, see [Sessions vs direct execution](/docs/sessions-vs-direct-execution) and the [migration guide](/docs/migration-guide/direct-to-sessions). You can inspect the selected tools, inputs, responses, and timing with the [Logs API](/reference/api-reference/logs).
skills/composio/SKILL.md
+1 -1
@@ -57,7 +57,7 @@ Do not turn an explanation, documentation lookup, or narrow bug fix into onboard
57 4. Reuse an existing Composio credential first: a `COMPOSIO_API_KEY`, a saved CLI login, or a saved agent identity. Only when the task needs Composio, no credential exists, and no human is available to log in, follow [Authenticate an unattended agent](https://docs.composio.dev/docs/agent-setup/unattended-authentication) and run `composio login --agent`. A mention of Composio is not a reason to create an account, and an agent account does not authorize anyone's apps.
58 5. Never invent toolkit or tool slugs. Discover them at runtime or with the CLI.
59 6. Do not build a provider OAuth flow. Composio returns a Connect Link when authentication is needed.
60 -7. Use sessions for new Platform integrations. Preserve the application's existing user identity and agent architecture.
60 +7. Use sessions for new Platform integrations. For auth-only use with tools the developer already owns, follow [managed authentication for your own tools](https://docs.composio.dev/docs/authentication/managed-auth-for-custom-tools.md): Connect Link + Proxy Execute, without fetching catalog tools. Preserve the application's existing user identity and agent architecture.
61 8. Keep credentials out of source control, URLs, logs, chat, and command output.
62 9. Get the log or request ID before diagnosing a failed tool call.
63 10. Prefer the smallest configuration that completes the current job. Keep toolkit filters, tag policies, approvals, Firewall hooks, Custom MCP toolkits, sandbox controls, custom auth, provider-specific hardening, and other advanced options out of the first path unless the request or existing code requires them. When the request does ask for one, such as "ask before sending" or "block prompt injection", use the documented feature instead of building a substitute in prompts or application code.
skills/composio/references/platform.md
+9 -4
@@ -73,6 +73,8 @@ Do not introduce another LLM framework solely to demonstrate Composio.
73
74 ## Integrate sessions
75
76 +If the application or MCP server already has its own tools and needs only per-user third-party authentication, follow [managed authentication for your own tools](https://docs.composio.dev/docs/authentication/managed-auth-for-custom-tools.md). Create a Connect Link with `session.authorize()`, then call provider endpoints with `composio.tools.proxyExecute()` in TypeScript or `composio.tools.proxy()` in Python. Keep the existing tool definitions and business logic. Skip `session.tools()` and catalog tool selection for this path. The proxy returns provider responses, not access or refresh tokens. Your application still authenticates its own callers.
77 +
78 A session is the runtime context for one application user. It carries identity, connections, tool scope, and sandbox configuration.
79
80 Trace the application's existing authenticated user or tenant ID and use that stable identifier. Do not add a parallel user system or share one placeholder identity across users.
@@ -210,13 +212,16 @@ Know the limits before promising a design: remote servers only (no local or STDI
212
213 ## Verify setup when relevant
214
213 -For a first-time setup or integration request, success means a programmatic, safe, read-only tool call from the developer's real execution path returns an actual provider result and a non-empty Composio log ID.
215 +For a first-time setup or integration request, verify a safe, read-only provider request from the developer's real execution path:
216 +
217 +- For auth-only integrations with existing tools, call a provider endpoint through Proxy Execute using the intended user's connected account. Verify a successful HTTP status and the expected provider response. Catalog tool discovery and a Composio tool log ID are not required for this path.
218 +- For catalog-tool integrations, discover the real toolkit and tool at runtime. Verify an actual provider result and a non-empty Composio log ID. If the current user is not connected, check the Instant Tools guide before assuming a connection is required.
219
215 -Ask which integration the developer wants to try unless the application already makes the choice clear. Discover the real toolkit and tool at runtime. If the current user is not connected, check the Instant Tools guide before assuming a connection is required. When authentication is required, return the Connect Link, wait for authorization, and retry.
220 +Ask which integration the developer wants to try unless the application already makes the choice clear. When authentication is required, return the Connect Link, wait for authorization, and retry.
221
217 -A mock, Playground run, tool search, schema fetch, session creation, or Connect Link alone does not prove the integration. If the repository has no runnable agent loop, add only the smallest entrypoint compatible with its existing provider; do not require another hosted model.
222 +A mock, Playground run, tool search, schema fetch, session creation, or Connect Link alone does not prove the integration. If the repository has no runnable execution path, add only the smallest entrypoint compatible with its existing runtime; do not require another hosted model.
223
219 -After success, report the code location, identity and session mapping, integration and tool, safe result summary, log ID, and useful dashboard destinations. For an explanation, migration plan, or narrow bug fix, use that task's own completion condition instead of forcing a new tool call.
224 +After success, report the code location, user and account mapping, session ID when used, and safe result summary. For auth-only integrations, include the provider endpoint and HTTP status. For catalog-tool integrations, include the tool and Composio log ID. For an explanation, migration plan, or narrow bug fix, use that task's own completion condition instead of forcing a new tool call.
225
226 ## Use canonical documentation
227