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: state the credential boundary where agents land
Brendan O'Leary committed
Oct 26, 2026 at 19:59 UTC
a4a449c23a43c0b397e96b4c5c74627e75e02a77
3 files changed
+17
-6
docs/app/llms.txt/route.ts
+2
@@ -31,6 +31,8 @@ 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.
35
+- [Proxy Execute](https://docs.composio.dev/docs/extending-sessions/proxy-execute.md): Call provider endpoints that tools don't cover without retrieving the token.
36
- [Configure sessions](https://docs.composio.dev/docs/configuring-sessions.md): Select toolkits, auth configs, and connected accounts for a user.
37
- [SDKs and frameworks](https://docs.composio.dev/docs/providers.md): Choose the provider for your agent framework.
38
- [Sessions via MCP](https://docs.composio.dev/docs/sessions-via-mcp.md): Give an application-created session to an MCP-compatible framework.
docs/components/home-features.tsx
+2
-2
@@ -46,8 +46,8 @@ export function HomeFeatures() {
46
visual={<ToolkitsVisual />}
47
/>
48
<FeatureCard
49
- title="Auth and context, per end-user."
50
- description="OAuth, API keys, and tokens scoped to each user and refreshed automatically."
49
+ title="Act for users without exposing their tokens."
50
+ description="Composio stores and refreshes each user's credentials. Your application and model receive tool results, not raw OAuth tokens."
51
href="/docs/authentication"
52
visual={<AuthDiagram />}
53
/>
docs/content/docs/authentication/index.mdx
+13
-4
@@ -1,7 +1,7 @@
1
---
2
title: Authentication
3
-description: Understand how Composio handles user authentication to toolkits
4
-keywords: [connect link, oauth, auth config, in-chat auth, dynamic auth]
3
+description: How Composio connects each user's accounts, where their credentials live, and how your app and model act on them without receiving OAuth tokens
4
+keywords: [connect link, oauth, auth config, in-chat auth, dynamic auth, token custody, credential isolation]
5
---
6
7
Composio organizes everything around your **users**. A user is whoever your agent acts on behalf of: a person in your app, identified by a [`userID`](/docs/how-composio-works) you choose. Authentication is always per user. Each user connects their own accounts, their Gmail, their GitHub, their Slack, and Composio stores and refreshes those credentials against that `userID`.
@@ -21,10 +21,19 @@ 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
-See [Token custody architecture](/docs/security/token-custody) for where credentials live, what your application receives, and how deployment options change custody.
25
-
24
<ManageConnectionsVisual />
25
26
+## Where credentials live
27
+
28
+When users connect through a Connect Link and your agent acts through tools, your application never handles their OAuth tokens. Composio stores each connected account's credentials encrypted at rest and refreshes OAuth tokens before they expire. When your agent calls a tool, your backend sends a user ID or connected account ID plus the tool arguments. Composio adds the credential to the provider request server-side and returns the provider's response. Your application and the model receive tool results, not tokens.
29
+
30
+- **No token export.** Connected-account API responses redact credentials by default, for both Composio-managed and custom auth configs. Reading account state isn't a supported way to retrieve tokens.
31
+- **Raw API access without the token.** For endpoints a tool doesn't cover, [Proxy Execute](/docs/extending-sessions/proxy-execute) sends an authenticated request to the provider and returns the response. It requires its own API key permission.
32
+- **Least-privilege keys and sessions.** [Scoped API keys](/reference/authenticating-to-composio/project-api-key-permissions) separate session management from tool execution, and [session configuration](/docs/configuring-sessions) limits which toolkits and tools an agent can call.
33
+- **Custody you choose.** In the default Composio Cloud deployment, Composio holds the encrypted credentials. Private VPC, self-hosted, and customer-managed key deployments change that boundary. With customer-managed keys, a proxy in your cloud decrypts credentials under your KMS keys, and Composio doesn't hold the key material.
34
+
35
+If you [import existing credentials](/docs/authentication/importing-existing-connections), your application handles those tokens once before sending them to Composio. See [Token custody architecture](/docs/security/token-custody) for the full request flow, redaction scope, and [deployment options](/docs/security/token-custody#deployment-options).
36
+
37
## How Composio handles authentication
38
39
Every session includes the [`COMPOSIO_MANAGE_CONNECTIONS`](/toolkits/meta-tools/manage_connections) meta tool. When a tool needs an account, it reads the toolkit's **auth config** (how that toolkit authenticates: method, scopes, credentials), creates a connection, and returns a secure [Connect Link](/reference/api-reference/connected-accounts/postConnectedAccountsLink). This works for all Composio managed connections, so you don't have to set up any OAuth credentials yourself.