@devries-cameron20 / composio Mirror · read-only / commits / ba58613bf
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 07:15 UTC

docs: explain managed authentication for application-owned tools

Brendan O'Leary committed Oct 29, 2026 at 18:31 UTC ba58613bf40ff011e669f1bed5e4e2bf80abac79
16 files changed +186 -25
docs/app/llms.mdx/[[...slug]]/route.ts
+2
@@ -1012,6 +1012,8 @@ async function generateManagedAuthIndex(): Promise<string> {
1012 '',
1013 'Composio can provide the OAuth app that your users authorize when they connect a toolkit. You do not need to register an OAuth app or supply its client ID and client secret.',
1014 '',
1015 + 'This catalog identifies who provides the OAuth app, not which execution framework you must use. For per-user OAuth with application-owned tools, follow [Managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools.md). Call provider endpoints through the authenticated proxy without predefined tools, MCP, or an LLM.',
1016 + '',
1017 'This list covers only toolkits that support OAuth. It does not include toolkits that use only API keys, bearer tokens, Basic auth, or no authentication.',
1018 '',
1019 'Call the toolkit endpoint and read `composio_managed_auth_schemes`:',
docs/app/llms.txt/route.ts
+3 -1
@@ -31,7 +31,9 @@ If it is unclear whether the goal is to integrate Composio into the application
31
32 - [Core concepts](https://docs.composio.dev/docs/how-composio-works.md): Understand users, sessions, toolkits, and tool execution.
33 - [Authentication](https://docs.composio.dev/docs/authentication.md): Distinguish auth configs from connected accounts and connect your application's users.
34 -- [Token custody](https://docs.composio.dev/docs/security/token-custody.md): Where credentials live, why your app and model get results instead of tokens, and VPC, self-hosted, and customer-managed key options.
34 +- [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.
35 +- [B2B agents](https://docs.composio.dev/docs/b2b-agents.md): Tenant/member connection ownership and authorization.
36 +- [Token custody](https://docs.composio.dev/docs/security/token-custody.md): Credential storage, redaction, VPC, self-hosting, and customer-managed keys.
37 - [Proxy Execute](https://docs.composio.dev/docs/extending-sessions/proxy-execute.md): Call provider endpoints that tools don't cover without retrieving the token.
38 - [Configure sessions](https://docs.composio.dev/docs/configuring-sessions.md): Select toolkits, auth configs, and connected accounts for a user.
39 - [SDKs and frameworks](https://docs.composio.dev/docs/providers.md): Choose the provider for your agent framework.
docs/content/docs/authentication/custom-app-vs-managed-app.mdx
+5 -3
@@ -11,19 +11,21 @@ Composio supports two ways to authenticate users with toolkits.
11
12 This page covers when to use each, how to create a custom auth config, and how to wire it into a session.
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 +
16 ## When to use Composio managed apps
17
16 -Managed apps are the default when they are available. Use them when:
18 +Managed apps are the default when they are available. Keep them in production when their consent branding, scopes, and shared provider quotas fit your product. Use them when:
19
20 - **You're building and iterating.** No OAuth app registration, no credentials to manage. Create a session and start testing immediately.
21 - **Default scopes cover your needs.** Composio requests sensible defaults for each toolkit.
20 -- **Branding on consent screens doesn't matter yet.** Users will see "Composio wants to access your account" during OAuth. Fine for internal tools, prototypes, and development. You can still [white-label the Connect Link page](/docs/authentication/white-labeling-authentication#customizing-the-connect-link) with your logo and app title without needing your own OAuth app.
22 +- **Composio branding on consent screens fits your product.** Users see Composio's app name during OAuth. You can still [white-label the Connect Link page](/docs/authentication/white-labeling-authentication#customizing-the-connect-link) with your logo and app title without needing your own OAuth app.
23
24 ## When to use a custom auth config
25
26 Bring your own credentials when any of these apply:
27
26 -- **Your users see OAuth consent screens.** In production, users should see your app name, not "Composio." This is the most common reason to switch.
28 +- **You need your app name on OAuth consent screens.** Use your own OAuth app when your product's branding requirements call for it.
29 - **You need custom scopes.** Composio's default scopes may not include everything you need (e.g., write access to a specific Google API).
30 - **You're hitting rate limits.** Managed apps share quota across all Composio users. Your own app gets a dedicated quota.
31 - **You need faster polling triggers.** Managed auth enforces a 2-minute minimum polling interval; your own app can use shorter polling intervals where supported.
docs/content/docs/authentication/index.mdx
+2
@@ -21,6 +21,8 @@ Because connections are stored under the `userID`, use a stable identifier, like
21
22 Your users connect their accounts through a secure [Connect Link](/reference/api-reference/connected-accounts/postConnectedAccountsLink), and Composio manages their tokens for you.
23
24 +Already have your own tools or agent framework? Follow [Managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools) to connect users and call provider APIs without handling their tokens. You don't need predefined Composio tools, MCP, or an LLM.
25 +
26 <ManageConnectionsVisual />
27
28 ## Where credentials live
docs/content/docs/authentication/managed-auth-for-custom-tools.mdx new
+146
@@ -0,0 +1,146 @@
1 +---
2 +title: Managed authentication for your own tools
3 +description: Connect each user's accounts and call provider APIs from your own tools without handling OAuth tokens
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 while keeping your tool definitions and business logic in your application. Call provider endpoints through Proxy Execute; Composio supplies the connected account's credentials and returns the response. You don't need predefined Composio tools, MCP, or an LLM.
8 +
9 +In Composio Cloud, the authenticated provider request still runs through Composio. Your function runs in your process, but Composio stores and refreshes credentials and sends the provider request. This is managed authentication for your own tools, not a token-export service.
10 +
11 +## Connect an account and call its API
12 +
13 +This example connects GitHub and reads the connected account's profile through `GET /user`. Install the SDK with `pip install composio` or `npm install @composio/core`. Set `COMPOSIO_API_KEY` in your backend environment. The API example also needs Bash and `jq`.
14 +
15 +Use a [project API key](/reference/authenticating-to-composio/project-api-key-permissions) with **Session management**, permission to read connected accounts, and **Proxy execute**. Proxy permission is separate from session tool execution. Keep the key server-side.
16 +
17 +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.
18 +
19 +<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
20 +<Tab value="Python">
21 +```python
22 +from composio import Composio
23 +
24 +composio = Composio()
25 +
26 +# Resolve this owner from your authenticated application session.
27 +owner_id = "org_42:user_7"
28 +session = composio.create(user_id=owner_id, toolkits=["github"])
29 +connection = session.authorize("github")
30 +print(f"Open this Connect Link: {connection.redirect_url}")
31 +account = connection.wait_for_connection(60)
32 +
33 +
34 +def read_github_profile(connected_account_id: str):
35 + return composio.tools.proxy(
36 + connected_account_id=connected_account_id,
37 + endpoint="/user",
38 + method="GET",
39 + )
40 +
41 +
42 +# Use the account returned by this owner's connection attempt.
43 +print(read_github_profile(account.id))
44 +```
45 +</Tab>
46 +<Tab value="TypeScript">
47 +```typescript
48 +import { Composio } from '@composio/core';
49 +
50 +const composio = new Composio();
51 +
52 +// Resolve this owner from your authenticated application session.
53 +const ownerId = 'org_42:user_7';
54 +const session = await composio.create(ownerId, { toolkits: ['github'] });
55 +const connection = await session.authorize('github');
56 +console.log(`Open this Connect Link: ${connection.redirectUrl}`);
57 +const account = await connection.waitForConnection(60000);
58 +
59 +function readGitHubProfile(connectedAccountId: string) {
60 + return composio.tools.proxyExecute({
61 + connectedAccountId,
62 + endpoint: '/user',
63 + method: 'GET',
64 + });
65 +}
66 +
67 +// Use the account returned by this owner's connection attempt.
68 +console.log(await readGitHubProfile(account.id));
69 +```
70 +</Tab>
71 +<Tab value="API">
72 +```bash
73 +set -euo pipefail
74 +
75 +# Resolve this owner from your authenticated application session.
76 +SESSION_ID=$(curl --fail-with-body -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
77 + -H "x-api-key: $COMPOSIO_API_KEY" \
78 + -H "Content-Type: application/json" \
79 + -d '{"user_id":"org_42:user_7","toolkits":{"enable":["github"]}}' | jq -r '.session_id')
80 +
81 +CONNECTION=$(curl --fail-with-body -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \
82 + -H "x-api-key: $COMPOSIO_API_KEY" \
83 + -H "Content-Type: application/json" \
84 + -d '{"toolkit":"github"}')
85 +echo "$CONNECTION" | jq -r '.redirect_url'
86 +CONNECTED_ACCOUNT_ID=$(echo "$CONNECTION" | jq -r '.connected_account_id')
87 +
88 +# Open the printed link. Wait at most 60 seconds for authorization.
89 +DEADLINE=$((SECONDS + 60))
90 +while true; do
91 + ACCOUNT=$(curl --fail-with-body -s https://backend.composio.dev/api/v3.1/connected_accounts/$CONNECTED_ACCOUNT_ID \
92 + -H "x-api-key: $COMPOSIO_API_KEY")
93 + STATUS=$(echo "$ACCOUNT" | jq -r '.status')
94 + case "$STATUS" in
95 + ACTIVE) break ;;
96 + FAILED|EXPIRED|INACTIVE|REVOKED) echo "Connection ended: $STATUS" >&2; exit 1 ;;
97 + esac
98 + if [ "$SECONDS" -ge "$DEADLINE" ]; then
99 + echo "Timed out waiting for authorization" >&2
100 + exit 1
101 + fi
102 + sleep 1
103 +done
104 +
105 +# Use the account returned by this owner's connection attempt.
106 +curl --fail-with-body -s -X POST https://backend.composio.dev/api/v3.1/tools/execute/proxy \
107 + -H "x-api-key: $COMPOSIO_API_KEY" \
108 + -H "Content-Type: application/json" \
109 + -d "{\"connected_account_id\":\"$CONNECTED_ACCOUNT_ID\",\"endpoint\":\"/user\",\"method\":\"GET\"}"
110 +```
111 +</Tab>
112 +</Tabs>
113 +
114 +Open the printed Connect Link and authorize GitHub within 60 seconds. The connection must become `ACTIVE` before the proxy request runs. The proxy returns the provider's response, not its OAuth token. No tool schemas are fetched and no model selects an action.
115 +
116 +The session above provides a user-scoped context for creating the connection. The final request uses the exact returned connected-account ID, so another GitHub connection cannot be selected accidentally. Your own tool can call `read_github_profile()` or `readGitHubProfile()` from any framework, or you can make the equivalent REST request from your backend.
117 +
118 +## Reuse connections in your application
119 +
120 +For onboarding or a settings page, send the Connect Link to the browser and persist the connection attempt server-side rather than holding an HTTP request open while the person signs in. On callback, verify that the connected-account ID belongs to that attempt and the signed-in owner, then retrieve its current status. Callback query parameters aren't proof of ownership. See [Manual auth management](/docs/authentication/manually-authenticating#identify-the-connected-account).
121 +
122 +Store the verified connected-account ID with your tenant/member mapping. On subsequent requests, authorize the caller and resolve that stored mapping before calling the proxy. Don't expose an endpoint that accepts arbitrary connected-account IDs from a browser or model.
123 +
124 +If authorization fails or times out, don't call the provider. If a connection expires or is revoked, stop using it and ask its owner to reconnect. Subscribe to the [connection expiration event](/docs/authentication#connection-lifecycle) to surface reconnect prompts before a request fails. Don't automatically retry side-effecting provider requests; see [retry failed executions deliberately](/docs/production-readiness#retry-failed-executions-deliberately).
125 +
126 +## Choose your OAuth app separately
127 +
128 +Keep Composio-managed OAuth apps in production when their consent branding, scopes, and shared provider quotas fit your product. Use a [custom auth config](/docs/authentication/custom-app-vs-managed-app) when you need your own OAuth app, different scopes, dedicated quotas, or a custom provider instance. Composio still manages the resulting connected-account credentials in either case.
129 +
130 +## Understand the boundaries
131 +
132 +<Callout type="warn" title="Managed authentication is not token export">
133 +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.
134 +</Callout>
135 +
136 +- **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.
137 +- **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.
138 +- **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.
139 +
140 +## Next
141 +
142 +<Cards>
143 + <Card title="Proxy Execute" href="/docs/extending-sessions/proxy-execute" description="Call provider endpoints from a session and understand proxy restrictions." />
144 + <Card title="Custom tools and toolkits" href="/docs/extending-sessions/custom-tools-and-toolkits" description="Optionally expose your custom business logic through experimental session extension tools." />
145 + <Card title="Token custody architecture" href="/docs/security/token-custody" description="Review credential redaction, OAuth app ownership, and deployment boundaries." />
146 +</Cards>
docs/content/docs/authentication/meta.json
+1
@@ -1,6 +1,7 @@
1 {
2 "title": "Authentication",
3 "pages": [
4 + "managed-auth-for-custom-tools",
5 "manually-authenticating",
6 "managing-multiple-connected-accounts",
7 "importing-existing-connections",
docs/content/docs/b2b-agents.mdx
+1
@@ -113,6 +113,7 @@ See [Subscribing to trigger events](/docs/setting-up-triggers/subscribing-to-eve
113 ## Next
114
115 <Cards>
116 + <Card title="Managed auth for your own tools" href="/docs/authentication/managed-auth-for-custom-tools" description="Keep your tool definitions and business logic while Composio authenticates provider requests." />
117 <Card title="Build a consumer agent" href="/docs/consumer-agents" description="Use a simpler per-person identity and connection model." />
118 <Card title="White-label authentication" href="/docs/authentication/white-labeling-authentication" description="Brand Connect Links, consent screens, domains, and callbacks." />
119 <Card title="Move to production" href="/docs/production-readiness" description="Review identity, auth, security, logging, and trigger decisions." />
docs/content/docs/extending-sessions/custom-tools-and-toolkits.mdx
+2
@@ -7,6 +7,8 @@ experimental: true
7
8 For a complete agent that combines an internal lookup with a public API, follow [Combine your own tools with Composio](/examples/custom-tools).
9
10 +If you already have your own tool definitions, start with [Managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools). You can call the authenticated proxy from your code without adopting the experimental session-extension API below.
11 +
12 Custom tools let you define tools that run in-process alongside remote Composio tools within a session. You have three patterns:
13
14 - **Standalone tools**: internal app logic that doesn't need Composio auth (DB lookups, in-memory data, business rules).
docs/content/docs/extending-sessions/proxy-execute.mdx
+2
@@ -10,6 +10,8 @@ The session is already scoped to a [userID](/docs/how-composio-works), so you pa
10
11 Proxy execute is a building block, not just a fallback. Use it to build experiences on top of Composio that reach past predefined tools, like the [Pi + Slack bot example](/examples/general-agent-with-pi#reach-the-gaps-with-the-proxy), which drops down to the proxy for the Slack Web API calls the toolkit doesn't wrap as tools. We'll link more examples here as we add them.
12
13 +For the complete connection-to-request flow in your own backend, follow [Managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools). It covers per-user OAuth, connection status, and account-specific proxy requests without an agent framework.
14 +
15 <Callout title="Use a scoped API key">
16 Authenticate with a [scoped project API key](/reference/authenticating-to-composio/project-api-key-permissions) that has **Proxy execute** enabled. Session tool execution alone does not cover `session.proxyExecute()` or proxy calls made from that session's sandbox. Default full-access keys already include this permission.
17 </Callout>
docs/content/kb/guide/platform-production-readiness.mdx
+5 -4
@@ -33,10 +33,11 @@ apps, scopes, or provider credentials differ.
33
34 ## Switch from managed auth only when production requirements call for it
35
36 -Composio managed auth is suitable for development, internal tools, and early
37 -prototypes. Create a custom auth config when users must see the application's
38 -own OAuth brand, the integration needs custom scopes or a dedicated provider
39 -quota, polling requirements differ, or the provider uses a custom instance.
36 +Keep Composio-managed OAuth apps in production when their consent branding,
37 +scopes, and shared provider quotas fit your product. Create a custom auth
38 +config when you need your application's own OAuth brand, custom scopes, a
39 +dedicated provider quota, different polling requirements, or a custom instance.
40 +Both options keep connected-account credential storage and refresh in Composio.
41 Pass the resulting auth config ID to the session; creating the config alone
42 does not make the session use it.
43
docs/content/toolkits/managed-auth.mdx
+2
@@ -8,6 +8,8 @@ Composio can provide the OAuth app that your users authorize when they connect a
8
9 Your users still authorize their accounts through a [Connect Link](/docs/tools-direct/authenticating-tools#hosted-authentication-connect-link). Composio stores and refreshes the resulting tokens. See [Authentication](/docs/authentication) for the full connection flow.
10
11 +This catalog identifies who provides the OAuth app, not which execution framework you must use. For per-user OAuth with application-owned tools, follow [Managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools). Your code can call provider endpoints through the authenticated proxy without predefined tools, MCP, or an LLM.
12 +
13 This page covers only toolkits that support OAuth. It does not list toolkits that use only API keys, bearer tokens, Basic auth, or no authentication.
14
15 ## When Composio provides the OAuth app
docs/kb/articles/platform-production-readiness.md
+5 -4
@@ -22,10 +22,11 @@ apps, scopes, or provider credentials differ.
22
23 ## Switch from managed auth only when production requirements call for it
24
25 -Composio managed auth is suitable for development, internal tools, and early
26 -prototypes. Create a custom auth config when users must see the application's
27 -own OAuth brand, the integration needs custom scopes or a dedicated provider
28 -quota, polling requirements differ, or the provider uses a custom instance.
25 +Keep Composio-managed OAuth apps in production when their consent branding,
26 +scopes, and shared provider quotas fit your product. Create a custom auth
27 +config when you need your application's own OAuth brand, custom scopes, a
28 +dedicated provider quota, different polling requirements, or a custom instance.
29 +Both options keep connected-account credential storage and refresh in Composio.
30 Pass the resulting auth config ID to the session; creating the config alone
31 does not make the session use it.
32
docs/kb/source/platform/production-readiness/public.md
+5 -4
@@ -39,10 +39,11 @@ apps, scopes, or provider credentials differ.
39
40 ## Switch from managed auth only when production requirements call for it
41
42 -Composio managed auth is suitable for development, internal tools, and early
43 -prototypes. Create a custom auth config when users must see the application's
44 -own OAuth brand, the integration needs custom scopes or a dedicated provider
45 -quota, polling requirements differ, or the provider uses a custom instance.
42 +Keep Composio-managed OAuth apps in production when their consent branding,
43 +scopes, and shared provider quotas fit your product. Create a custom auth
44 +config when you need your application's own OAuth brand, custom scopes, a
45 +dedicated provider quota, different polling requirements, or a custom instance.
46 +Both options keep connected-account credential storage and refresh in Composio.
47 Pass the resulting auth config ID to the session; creating the config alone
48 does not make the session use it.
49
docs/lib/home-navigation.ts
+1
@@ -188,6 +188,7 @@ export const DOCS_PRODUCTS = {
188 label: 'Authentication',
189 links: [
190 { url: '/docs/authentication', label: 'Authentication with Composio' },
191 + { url: '/docs/authentication/managed-auth-for-custom-tools' },
192 {
193 url: '/docs/authentication/managing-multiple-connected-accounts',
194 label: 'Multiple connected accounts',
docs/lib/llm-guardrails/session.ts
+3 -1
@@ -28,7 +28,9 @@ export const SESSION_GUARDRAILS = `
28
29 ## 1. Recommended Integration: Sessions
30
31 -Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed).
31 +For agent tool delivery, Composio supports **Native Tools** (with a provider package) and **MCP** (no provider package needed).
32 +
33 +For application-owned tools or deterministic backend code, use [managed authentication with Proxy Execute](/docs/authentication/managed-auth-for-custom-tools). A session can provide a user-scoped runtime context without an LLM or MCP. Composio authenticates provider requests server-side; connected-account reads redact credentials and aren't a supported token-export workflow.
34
35 ### Native Tools
36
docs/tests/static/sidebar-nav-index.test.ts
+1 -8
@@ -77,15 +77,8 @@ describe('buildSidebarNavIndex', () => {
77 expect(index['/docs/how-composio-works'].position).toBe(1);
78 });
79
80 - test("a folder's children start their own sequence", () => {
81 - expect(index['/docs/authentication/manually-authenticating'].position).toBe(1);
82 - expect(index['/docs/extending-sessions/proxy-execute'].position).toBe(1);
83 - });
84 -
80 test('a folder counts as one entry for its siblings', () => {
86 - // Authentication holds 7 children, so a counter that threaded through them
87 - // would put Triggers 7 sibling slots later than Authentication instead of
88 - // directly after it.
81 + // A folder's children must not advance the parent-level position counter.
82 expect(index['/docs/triggers'].position).toBe(index['/docs/authentication'].position + 1);
83 expect(index['/docs/skills'].position).toBe(index['/docs/triggers'].position + 1);
84 });