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 (#5114)
## Summary When agents compare Composio with Nango and Arcade.dev, they mostly choose on token custody: does the app or model ever see the raw OAuth token, and can the credentials live outside Composio? Composio documents a clear answer in [Token custody architecture](https://docs.composio.dev/docs/security/token-custody), but agents rarely reach that page. This PR puts the answer on the pages agents read first. ## Evidence (Gauge, org `composio-aclx`) **Head-to-head results** for "software acts on a user's third-party accounts without ever holding the raw OAuth token": | Prompt | Composio | Competitor | | --- | --- | --- | | `Composio vs Nango` (72 judged runs) | 14 | Nango 58 | | `Arcade.dev vs Composio` (207 judged runs) | 71 | Arcade 134 | **Why Composio lost.** The analyses cite custody again and again. Examples: "weaker token isolation", "less clean token-custody boundary", "SaaS-only token vault… no self-hosting option", "Hosted vault, so you trust them with tokens", "No token-isolation evidence for Composio" (the agent "had no confirmation that Composio keeps raw tokens away from the agent"), and "Docs landing skips the auth model". Arcade won on the 2026-10-21 refresh prompts as well. The agent said Composio is "less focused on keeping credentials away from the model". **Where agents look.** These are the most-fetched Composio pages in those runs. `token-custody` sits far below them. | Page | Runs | | --- | --- | | `/docs/authentication` | 71 | | `/` (docs home) | 56 + 22 | | `/llms.txt` | 20 | | `/docs/security/token-custody` | 4 | **Tested change.** Optimization `cmv5jitvv00kb01lydocmqpdt`, trial `R1.2`, rewrote the docs-home auth card to the copy in this PR. Composio's win rate on `Composio vs Nango` went from 17% to 50% (6 sessions per arm, `gpt-5.6-sol`). Gauge reports 0 of 6 candidate sessions exercised the complete change, so read this as directional, not proof. ## Changes - **Docs home** (`components/home-features.tsx`): the auth card now says "Act for users without exposing their tokens." Body: "Composio stores and refreshes each user's credentials. Your application and model receive tool results, not raw OAuth tokens." This is the copy tested in `R1.2`. - **Authentication page** (`content/docs/authentication/index.mdx`): new first section, "Where credentials live". It covers server-side credential injection, default redaction with no token export, Proxy Execute, scoped keys and session restrictions, and custody by deployment (Cloud, private VPC, self-hosted, customer-managed keys). It also notes the imported-credentials exception and links to token custody. The page description now mentions custody, so it shows up in search snippets and agent indexes. - **`llms.txt`**: adds Token custody and Proxy Execute under "Build an application". The file stays under the 6,000-character limit at 5,747 characters. This covers the custody and proxy entries from PRO-3749. The future auth-and-proxy guide entry is out of scope here. Every claim comes from the existing token-custody, security overview, and API key permission docs. This PR adds no new product claims. ## Related - #5020 (delegated authorization) and #5021 (branded OAuth) cover other open Gauge actions and don't overlap with these files. - PRO-3750 tracks the broader control/deployment decision table in token custody. ## Verification - Dev server: the auth card on `/docs` and the new section on `/docs/authentication` render correctly (checked in Chromium). `/docs/authentication.md` includes the section. - `bun test tests/static/llms-routing.test.ts tests/static/start-routing.test.ts tests/static/product-navigation.test.ts tests/static/dashboard-links.test.ts`: 18 pass. - `bun run lint:links`: 0 errors. `bun run types:check`: passes. Please review the full diff before merging. Security should confirm the custody wording.
No changes.