@devries-cameron20 / composio-1 / commits / 1fc94ac5e
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: clarify credential control and retention choices (#5456)

## Summary Security reviewers need to distinguish control of tool logic, OAuth apps, tokens, runtime, and stored payloads. Existing docs already disclose Cloud custody and retention tradeoffs. This draft organizes those facts and preserves the limits. Related: [DEVREL-315](https://linear.app/composio/issue/DEVREL-315/cloud-stores-tokens-and-payloads-by-default), [PRO-3750](https://linear.app/composio/issue/PRO-3750/document-control-over-tools-credentials-and-deployment-as-explicit). These issues remain open; this does not establish that their Gauge acceptance criteria have passed. Designated reviewer: @jkomyno. Product/security questions are below for Brendan to route. ## Changes - Add a seven-row table of controls to the existing token-custody page, with links to each documented control and its limits. - Add a short payload-location and retention summary, including log/file lifetimes and ZDR exclusions. - Link the table from the own-tools auth guide and B2B architecture, keeping the custody page as the single reference. - Replace the vendor-review page's retired **Don't store data** name with current ZDR guidance. Link its training explanation to the existing payload and de-identified metadata policy. | Before | After | | --- | --- | | Control choices spread across authentication, security, and B2B pages | One linked table distinguishes app control, Composio operation, and limits | | Custody page links out for all retention lifetimes | Short, sourced summary preserves the detailed policy links | | Vendor review uses a retired setting name and only a blanket training caution | Current ZDR name and explicit first-party policy, with metadata and downstream-provider qualifications | ## Existing facts and sources Sources below are pinned to the unchanged `next` revision used for this draft. Each new factual statement links to existing docs in the page itself. This is an inventory of documented behavior, not a backend security audit. | Area | Source | What the source establishes | | --- | --- | --- | | Cloud credentials and provider calls | [Existing custody flow](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/token-custody.mdx#L7) | Composio stores credentials and uses them server-side. Encryption and response redaction do not remove that custody. | | Application-owned tools and provider permissions | [Own-tools auth](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/authentication/managed-auth-for-custom-tools.mdx#L7); [Proxy permission](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/reference/authenticating-to-composio/project-api-key-permissions.mdx#L255) | Tool definitions and business logic can stay in the app. Proxy Execute still uses Composio and requires its own permission. | | OAuth app ownership | [Managed vs custom auth](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/authentication/custom-app-vs-managed-app.mdx#L18) | Branding, scopes, and provider quota change; token custody does not. | | Connection ownership and experimental APIs | [B2B ownership](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/b2b-agents.mdx#L9); [Shared connections](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/extending-sessions/shared-connections.mdx#L1); [Local tools](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/extending-sessions/local-tools-and-toolkits.mdx#L1) | The app maps tenants/members and authorizes callers. Shared connections and optional session extensions remain experimental. | | Credential retrieval and exit | [Credential masking](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/auth-configuration/connected-accounts.mdx#L258); [Existing export boundary](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/token-custody.mdx#L91) | Get/List account responses redact secrets and are not a supported raw-token export workflow. No migration or no-reconsent guarantee is added. | | Payloads and retention | [Data policy](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/data-retention.mdx#L15) | Default payload logging; logs up to one year; execution logs deleted within 30 days of organization deletion; staged files deleted after 24 hours, separately from URL expiry. | | ZDR coverage and exclusions | [ZDR policy](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/zero-data-retention.mdx#L7) | Paid-plan/Enterprise availability, new covered calls only, audit metadata retained, managed OAuth coverage only on Enterprise, and separate trigger/sandbox/file/search/third-party limits. | | Training | [Model-training policy](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/data-retention.mdx#L27) | Payloads excluded on every plan; de-identified execution metadata may train models and be retained indefinitely. Third-party terms remain separate. | | Deployment and customer-managed keys | [Existing deployment table](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/token-custody.mdx#L115); [SDK public transfer-key API](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/ts/packages/core/src/models/Keyring.ts#L31) | Existing Cloud/private VPC/self-hosted/customer-managed-key descriptions are preserved. The SDK proves public transfer-key retrieval, not operator access or plaintext boundaries. Current orderability and deployment details need product/security confirmation. | ## Relationship to the security and BYOC work - Builds on merged [#5372](https://github.com/ComposioHQ/composio/pull/5372). Its Security and Compliance navigation, routes, and existing policy pages remain in place. - [#5254](https://github.com/ComposioHQ/composio/pull/5254) is open and unmerged as inspected November 18. It owns the BYOC launch guide, customer-operated Helm retirement wording, deployment-table replacement, and detailed operator responsibilities. - **No merge dependency on #5254.** This change targets `next`, adds no BYOC route or launch promise, and leaves the deployment table unchanged. Applying #5254's token-custody patch over this edit passes `git apply --check`. Its replacement table remains the place for deployment availability when it lands. Recheck the combined wording before either PR ships. - No competitor comparison, landing-site change, SDK behavior change, manual deployment, or production/customer-data mutation. No Gauge rerun was performed; no preference improvement or resolved security objection is claimed. ## How Has This Been Tested? Run from `docs/` with Bun 1.4.2 and Node 24.22.1: - `bun install --frozen-lockfile`: passed; no lockfile change. - `bun run lint:links`: passed, 0 errored files / 0 errors for site and SDK links. - `bun run lint`: passed, with warnings in unchanged site files. - `bun run test --timeout 30000`: 838 passed, 0 failed across 80 files. - `git diff --check`: passed. - `GITHUB_ACTIONS=true timeout 20m bun run build`: passed under the shared build lock. MDX compilation, TypeScript, and generation of 2,662 static pages passed. Removed this worktree's 759 MB `.next` output afterward. An independent read-only agent checked the source inventory and final prose diff and found no blocking factual inaccuracies. No new tests are needed for prose-only changes; existing documentation checks cover links, MDX, and site behavior. ## NEEDS BRENDAN - **Product/security:** Which private VPC, customer-operated self-hosted, and customer-managed-key options are currently orderable? Confirm the boundary between current offerings and #5254's pending BYOC launch, including supported regions, control-plane location, operator/support access, keys, logs/backups, and required outbound traffic. The existing deployment descriptions are retained, not newly verified product promises. - **Security:** Where does Cloud store credentials, payloads, files, logs, and backups geographically? What are the credential and backup retention/deletion schedules after disconnect or organization deletion? The documented 30-day execution-log deletion window does not establish credential deletion. - **Security:** Reconcile ZDR's [no-PII statement](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/zero-data-retention.mdx#L103) with the [audit-log email/IP fields](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/audit-logs.mdx#L28) and provider error text in telemetry. What retention and redaction guarantees apply to those records? This draft does not repeat the blanket no-PII claim. - **Product/security:** Is any credential-transfer/exit process supported by agreement? Confirm provider/client ownership, possible re-consent, deletion/revocation of old copies, and migration steps before promising export or a seamless exit. ## Type of change - [x] Documentation ## Checklist - [x] Agent reviewed the full diff and preserved unrelated work. - [x] New claims trace to existing docs; unverified claims stay in owner questions. - [x] Existing security disclosures and third-party limits retained. - [x] No changeset required for documentation-only changes. - [ ] Brendan has reviewed every line. - [ ] Product/security has answered the questions above. ## In plain language You can keep your own tool logic and OAuth app while Composio still holds the tokens and sends provider requests. The docs now show those choices together and explain what ZDR changes, what stays stored, and which deployment questions need a specific agreement. <!-- sdk-release-note-exempt: This pull request changes only documentation and does not change published SDK behavior. -->

Brendan O'Leary committed Nov 18, 2026 at 10:11 UTC 1fc94ac5e0e790859ec9957d2ebeff82d2aa4c6e
4 files changed +28 -2
docs/content/docs/authentication/managed-auth-for-custom-tools.mdx
+2
@@ -141,6 +141,8 @@ Keep Composio-managed OAuth apps in production when their consent branding, scop
141
142 ## Understand the boundaries
143
144 +Use the [table of controls](/docs/security/token-custody#choose-your-controls) to compare tool ownership, OAuth scopes, connection ownership, credential export, deployment, and payload retention.
145 +
146 <Callout type="warn" title="Managed authentication is not token export">
147 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.
148 </Callout>
docs/content/docs/b2b-agents.mdx
+2
@@ -89,6 +89,8 @@ Your application remains responsible for deciding which members may ask the work
89
90 ## Choose the customer's authentication model
91
92 +Review the [table of controls](/docs/security/token-custody#choose-your-controls) before choosing OAuth app ownership, credential custody, deployment, and retention. Your application still authorizes each member's access to member-owned and workspace-owned connections.
93 +
94 Start with managed auth when Composio's provider app and scopes fit the product. Use [custom auth configs](/docs/authentication/custom-app-vs-managed-app) when your product needs its own OAuth branding, scopes, provider quotas, or self-hosted instances.
95
96 If each customer supplies different OAuth credentials, create and manage auth configs programmatically, then assign the right config when creating that customer's sessions. See [Programmatic auth configs](/docs/authentication/programmatic-auth-configs).
docs/content/docs/security/token-custody.mdx
+22
@@ -112,6 +112,20 @@ For custom business logic, [session extension tools](/docs/extending-sessions/lo
112
113 A [custom auth config](/docs/authentication/custom-app-vs-managed-app) lets you use your own OAuth app for branding, scopes, and provider quota. In Composio Cloud, Composio still stores and uses the resulting connected-account tokens. Owning the OAuth app does not move the token store into your infrastructure or change default API redaction.
114
115 +## Choose your controls
116 +
117 +Choose tool behavior, OAuth app ownership, credential custody, and retention separately. The table describes Composio Cloud unless a row points to a separate deployment arrangement.
118 +
119 +| Choice | What your application controls | What Composio operates and the limits |
120 +| --- | --- | --- |
121 +| Tool schemas and business logic | Keep your tool definitions and input validation in your application with [managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools). Select the predefined tools exposed through [sessions](/docs/configuring-sessions). | Proxy Execute authenticates provider requests without requiring predefined tool schemas, MCP, or an LLM. The optional [local session-extension API](/docs/extending-sessions/local-tools-and-toolkits) is experimental. |
122 +| OAuth app and provider scopes | Use [your own OAuth app](/docs/authentication/custom-app-vs-managed-app) for branding, scopes, and dedicated provider quota. Managed apps can request only the scopes their app supports. | Composio stores the resulting connected-account credentials and handles token refresh where supported. The provider grants the authorization. |
123 +| Member or workspace connection ownership | Choose a stable `user_id` and enforce [tenant membership and roles](/docs/b2b-agents#choose-the-connection-owner) before selecting an account. | Composio associates connections with the supplied ID. That ID is not proof of identity. [Shared connections](/docs/extending-sessions/shared-connections) use explicit access-control lists and are experimental. |
124 +| Credential retrieval and portability | Call tools or Proxy Execute using connected-account IDs. Review any workflow that [imports existing credentials](/docs/authentication/importing-existing-connections). | [Connected-account reads redact credentials](/docs/auth-configuration/connected-accounts#credential-masking). They are not a supported raw-token export workflow, including with your own OAuth app. |
125 +| Provider operations | Restrict [project API-key permissions](/reference/authenticating-to-composio/project-api-key-permissions), provider scopes, and the endpoints your code accepts. | Proxy Execute requires its own permission and can call operations beyond predefined tool schemas. Its [provider URL restrictions](/docs/tools-direct/executing-tools#proxy-execute) still apply. |
126 +| Execution location and key custody | Review the operator, decryption access, logs, backups, and outbound connections for your required environment. | Cloud hosts storage and execution by default. Other deployment choices require agreement with Composio; see [deployment options](#deployment-options) for availability and limits. |
127 +| Payload retention | Have an organization admin enable [Zero Data Retention](/docs/security/zero-data-retention) for the projects that need it. Review your own logs and downstream providers separately. | ZDR is available on paid plans and included on Enterprise. It suppresses new covered execution-log payloads, keeps metadata, and has [feature and managed-app exclusions](/docs/security/zero-data-retention#what-zdr-does-not-cover). It does not change credential custody. |
128 +
129 ## Deployment options
130
131 | Option | Credential boundary | Availability |
@@ -137,4 +151,12 @@ Your backend must bind the signed-in user to the correct Composio `user_id` and
151
152 Credential redaction and payload retention are separate controls. Tool arguments and results are stored in execution logs by default. A project's [Zero Data Retention](/docs/security/zero-data-retention) setting stops storage of new call payloads for covered calls while retaining audit metadata. It does not prevent processing during execution, delete existing logs, or govern your own logs and model provider. See [data retention](/docs/security/data-retention) for file storage, Workbench processing, and retention details.
153
154 +### Where payloads go and how long they stay
155 +
156 +The [data-handling policy](/docs/security/data-retention#where-your-data-goes) describes processing by Composio's execution infrastructure, destination providers, and any enabled file, trigger, or sandbox paths. Keeping provider tokens out of your application does not keep tool arguments and results out of those paths.
157 +
158 +- [Tool execution and trigger event logs](/docs/security/data-retention#how-long-logs-are-retained) are retained for up to one year. Organization deletion removes execution logs, including request and response payloads, within 30 days.
159 +- [Staged files](/docs/security/data-retention#how-long-files-are-available) are deleted after 24 hours. Presigned URLs expire after one hour by default; URL expiry does not delete the file.
160 +- [ZDR coverage](/docs/security/zero-data-retention#what-zdr-covers) applies to new covered tool and proxy calls. Composio-managed OAuth apps are covered only on Enterprise. Triggers, sandbox state, files, search caching, and third-party retention have [separate limits](/docs/security/zero-data-retention#what-zdr-does-not-cover). Audit logs and telemetry [remain stored](/docs/security/zero-data-retention#always-stored).
161 +
162 For compliance reports and the current sub-processor list, use the [Composio Trust Center](https://trust.composio.dev).
docs/content/docs/security/vendor-security-review.mdx
+2 -2
@@ -12,7 +12,7 @@ keywords: ["compliance", "platform", "privacy", "retention", "security"]
12
13 ## Zero data retention and no-training requirements
14
15 -Standard plans do not guarantee end-to-end zero data retention or zero training. The per-project **Don't store data** setting reduces what Composio stores, but it does not govern data retained or processed by third-party providers.
15 +The per-project [Zero Data Retention](/docs/security/zero-data-retention) setting suppresses new covered execution-log payloads while retaining metadata. It is available on paid plans and included on Enterprise, with [coverage limits](/docs/security/zero-data-retention#what-zdr-does-not-cover). It does not govern data retained or processed by third-party providers.
16
17 The [standard DPA](https://composio.dev/legal/dpa) is available to Pro and Enterprise Developer customers. An organization admin can review and accept it in Organization Settings > Billing > Data Processing Addendum. Acceptance is click-through; no countersignature is required.
18
@@ -20,7 +20,7 @@ For bespoke data-processing terms or an end-to-end contractual no-training requi
20
21 ## Model training
22
23 -Do not infer a blanket no-training guarantee. Features that use third-party providers are also governed by those providers' terms. For an end-to-end contractual no-training requirement, use the Enterprise track.
23 +Composio's [model-training policy](/docs/security/data-retention#model-training) excludes request arguments, response data, and trigger payloads from model training on every plan. Composio may use de-identified execution metadata to train models and keep it indefinitely. Features that use third-party providers are also governed by those providers' terms. For an end-to-end contractual no-training requirement, use the Enterprise track.
24
25 ## FedRAMP
26