@devries-cameron20 / composio Mirror · read-only / commits / 0536957a3
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, 13:30 UTC

docs: explain token custody architecture and deployment options

Brendan O'Leary committed Sep 11, 2026 at 14:44 UTC 0536957a38dbd89b75d38f0719f8715004629661
5 files changed +116 -34
docs/content/docs/auth-configuration/connected-accounts.mdx
+3 -33
@@ -82,39 +82,9 @@ console.log('Toolkit:', account.toolkit.slug);
82
83 ### Get account credentials
84
85 -Get account credentials for use with your own tools:
85 +Connected-account responses describe the authentication state. Sensitive credential fields in `account.state.val` are [redacted by default](#credential-masking), for both Composio-managed and custom auth configs. This object is not a source of usable provider tokens for your own tools.
86
87 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
88 - <Tab value="Python">
89 -```python
90 -# Get the connected account's authentication state
91 -if account.state:
92 - # The state contains the auth scheme and credentials
93 - auth_scheme = account.state.auth_scheme
94 - credentials = account.state.val
95 -
96 - print(f"Auth scheme: {auth_scheme}")
97 - print(f"Credentials: {credentials}")
98 -```
99 - </Tab>
100 - <Tab value="TypeScript">
101 -```typescript
102 -import { Composio } from '@composio/core';
103 -const composio = new Composio({ apiKey: 'your_api_key' });
104 -const account = await composio.connectedAccounts.get('ca_123');
105 -// ---cut---
106 -// Get the connected account's authentication state
107 -if (account.state) {
108 - // The state contains the auth scheme and credentials
109 - const authScheme = account.state.authScheme;
110 - const credentials = account.state.val;
111 -
112 - console.log('Auth scheme:', authScheme);
113 - console.log('Credentials:', credentials);
114 -}
115 -```
116 - </Tab>
117 -</Tabs>
87 +To call a provider API, use [Proxy Execute](/docs/extending-sessions/proxy-execute), which injects credentials server-side. For custom business logic, use [session extension tools](/docs/extending-sessions/custom-tools-and-toolkits). See [Token custody architecture](/docs/security/token-custody) for the boundaries between your application, Composio, and the provider.
88
89 ## Refresh credentials
90
@@ -236,7 +206,7 @@ Instead of returning full values, the API returns the first 4 characters followe
206
207 Values shorter than 4 characters are replaced with `REDACTED`.
208
239 -This applies to the Get Connected Account and List Connected Accounts endpoints.
209 +This applies to the Get Connected Account and List Connected Accounts endpoints for both Composio-managed and custom auth configs. The API redacts these fields before returning the response to your application.
210
211 If your use case requires calling a provider API directly, use [Proxy execute](/docs/extending-sessions/proxy-execute). Composio injects the connected account's credentials server-side.
212
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 +See [Token custody architecture](/docs/security/token-custody) for where credentials live, what your application receives, and how deployment options change custody.
25 +
26 <ManageConnectionsVisual />
27
28 ## How Composio handles authentication
docs/content/docs/security/meta.json
+2 -1
@@ -2,6 +2,7 @@
2 "title": "Security and data",
3 "defaultOpen": false,
4 "pages": [
5 - "overview"
5 + "overview",
6 + "token-custody"
7 ]
8 }
docs/content/docs/security/overview.mdx
+2
@@ -18,6 +18,8 @@ Composio is SOC 2 Type II compliant. For our latest reports and certifications (
18
19 ## Credential protection
20
21 +See [Token custody architecture](/docs/security/token-custody) for credential boundaries, server-side execution, default API redaction, and deployment options.
22 +
23 - Connected-account credentials, auth configs, and API keys are encrypted at rest using AES-256-GCM, and all traffic is encrypted in transit using TLS.
24 - Connected-account tokens are redacted by default in API responses, for both Composio-managed and custom auth configs. To act on a provider directly, use [Proxy Execute](/docs/extending-sessions/proxy-execute).
25 - Webhook deliveries are signed; verify the `webhook-signature` header when handling trigger events. For custom OAuth webhook setup, see [Custom OAuth webhooks](/docs/setting-up-triggers/custom-oauth-webhooks).
docs/content/docs/security/token-custody.mdx new
+107
@@ -0,0 +1,107 @@
1 +---
2 +title: Token custody architecture
3 +description: Where provider credentials live, how Composio injects them during execution, what API redaction covers, and how deployment choices change custody.
4 +keywords: [token custody, credential isolation, token redaction, OAuth, proxy execute, self-hosting, VPC, customer-managed keys]
5 +---
6 +
7 +Composio stores provider credentials and uses them to execute requests on your behalf. With hosted authentication and managed execution, your application passes account identifiers and tool arguments. Composio resolves the credentials and authenticates the provider request server-side.
8 +
9 +In the default Composio Cloud deployment, Composio has custody of those credentials. Keeping a token out of your application and keeping it outside Composio's infrastructure are different requirements. The [deployment options](#deployment-options) below describe that distinction.
10 +
11 +For example, after connecting a GitHub account, your backend can call GitHub through [Proxy Execute](/reference/api-reference/tools/postToolsExecuteProxy):
12 +
13 +```bash
14 +curl --request POST \
15 + --url https://backend.composio.dev/api/v3.1/tools/execute/proxy \
16 + --header "x-api-key: $COMPOSIO_API_KEY" \
17 + --header 'Content-Type: application/json' \
18 + --data '{
19 + "connected_account_id": "ca_your_github_account",
20 + "endpoint": "/user",
21 + "method": "GET"
22 + }'
23 +```
24 +
25 +Replace the account ID with your connected account. `COMPOSIO_API_KEY` must belong to that project and have the **Proxy execute** permission. The request contains a Composio API key, which authorizes execution, but no GitHub token. Composio injects that token and returns the provider response.
26 +
27 +## Token boundaries in Composio Cloud
28 +
29 +The following flow covers hosted OAuth and execution through Composio:
30 +
31 +```mermaid
32 +sequenceDiagram
33 + participant U as User's browser
34 + participant A as Your backend
35 + participant C as Composio Cloud
36 + participant P as Provider
37 + A->>C: Create hosted Connect Link
38 + C-->>U: Connect Link via your application
39 + U->>P: Sign in and grant consent
40 + P-->>C: OAuth authorization callback
41 + C->>P: Exchange authorization code
42 + P-->>C: Access and refresh tokens
43 + Note over C: Store encrypted credentials
44 + A->>C: API key, account or session ID, arguments
45 + Note over C: Resolve account and inject credential
46 + C->>P: Authenticated API request
47 + P-->>C: Provider response
48 + C-->>A: Execution result
49 +```
50 +
51 +The browser participates in consent. Your backend receives connection status and identifiers. Composio stores the provider credentials, handles refresh where supported, and uses them during execution. The provider receives the credential needed to authenticate its API call.
52 +
53 +Your model receives the tool definitions and results your application or MCP client supplies. Provider credentials are not required in prompts, tool arguments, or model context. A Composio API key is still a secret with permission to act on connected accounts, so keep it in your trusted backend or client credential store.
54 +
55 +The [security overview](/docs/security/overview#credential-protection) documents AES-256-GCM encryption at rest and TLS in transit. Encryption at rest protects stored credentials; the execution service still needs to use them to authenticate requests.
56 +
57 +## Default redaction is an API boundary
58 +
59 +Get Connected Account and List Connected Accounts redact sensitive credential fields by default. This applies to both Composio-managed and custom auth configs. Redaction happens in API responses before your application receives them; it does not depend on your application masking a token after retrieval.
60 +
61 +The response can still contain an authentication-state object such as `account.state.val`, including field names such as `access_token`. The presence of those fields in an SDK type or response schema does not establish that the API returns usable secrets or provides an unmasking option. See [credential masking](/docs/auth-configuration/connected-accounts#credential-masking) for the response format.
62 +
63 +Use tool execution or Proxy Execute when you need to act on an account. Reading connected-account state is not a supported token-export workflow.
64 +
65 +This redaction has a specific scope. It does not sanitize every provider response, a secret your own code supplies, or every log your application writes. Tool results can contain sensitive business data even when the authentication token stays inside the execution service.
66 +
67 +## Execution paths
68 +
69 +| Path | Where code runs and credentials are used |
70 +| --- | --- |
71 +| Native tools through a session, MCP, or direct execution | Composio executes the provider call and supplies the connected account's credential. Your caller receives the result. |
72 +| Proxy Execute | Composio authenticates an HTTP request to the connected provider. Use this for endpoints or request shapes that predefined tools do not cover. |
73 +| Session extension tools | Your custom function runs in your process. Its `ctx.proxyExecute()` or `ctx.proxy_execute()` call delegates authentication and the provider request to Composio. |
74 +| Independent local tools or imported credentials | Your code controls any secrets it reads or supplies. Importing an existing token means your application already handles that token before sending it to Composio. |
75 +
76 +[Sessions](/docs/configuring-sessions) and [direct execution](/docs/sessions-vs-direct-execution) also work from deterministic backend code. An LLM is not required to execute a tool or proxy request.
77 +
78 +[Proxy Execute](/docs/extending-sessions/proxy-execute) checks the destination against the connected account's toolkit domain and requires its own API-key permission. Use relative provider paths and let Composio supply authentication. Granting proxy access allows provider operations beyond predefined tool schemas, subject to the provider's permissions. Review that permission separately from tool selection.
79 +
80 +For custom business logic, [session extension tools](/docs/extending-sessions/custom-tools-and-toolkits) let your code call the proxy without reading tokens. If you instead [import credentials](/docs/authentication/importing-existing-connections) or handle authentication yourself, include those code paths in your credential review.
81 +
82 +## OAuth app ownership and token custody
83 +
84 +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.
85 +
86 +## Deployment options
87 +
88 +| Option | Credential boundary | Availability |
89 +| --- | --- | --- |
90 +| Composio Cloud | Composio hosts credential storage and execution. Your application calls the managed API. | Default hosted deployment. |
91 +| Private VPC deployment | Places the deployment within a private network boundary. Credential storage, operator access, and key ownership must be specified in the deployment design. | Enterprise arrangement. |
92 +| Self-hosted deployment | Runs Composio in your environment. Your team takes responsibility for the agreed infrastructure and operations. | Enterprise arrangement, with Helm deployment support. |
93 +| Customer-managed key deployment | A proxy in your cloud handles credential plaintext under keys in your KMS. Composio retains the control plane without the key material needed to decrypt those credentials. | Set up with the Composio team, rather than enabled by a dashboard toggle. |
94 +
95 +The [Enterprise overview](https://composio.dev/enterprise) and [MCP gateway deployment options](https://composio.dev/mcp-gateway) describe private and self-hosted availability. The [Helm troubleshooting guide](/kb/guide/platform-self-hosted-helm) covers existing self-hosted installations.
96 +
97 +The [customer-managed key architecture](https://composio.dev/blog/two-questions-every-security-review-asks-us) supports AWS KMS, Google Cloud KMS, and HashiCorp Vault Transit. This is a separate deployment choice from bringing your own OAuth app.
98 +
99 +If your requirement is that Composio cannot decrypt provider credentials, evaluate the customer-managed key arrangement with the team. For VPC or self-hosted deployments, confirm who operates each service, who can decrypt credentials, where logs and backups reside, and which outbound connections are required. A deployment label alone does not answer those questions. [Contact Composio](https://composio.dev/contact?utm_source=docs) to establish the architecture and contractual requirements.
100 +
101 +## Application authorization and retained data
102 +
103 +Your backend must bind the signed-in user to the correct Composio `user_id` and connected accounts. A caller-supplied user ID is not proof of identity. Choose [provider scopes](/docs/authentication/controlling-scopes), [session tools](/docs/configuring-sessions), and [API-key permissions](/reference/authenticating-to-composio/project-api-key-permissions) for the operations your application needs.
104 +
105 +Credential redaction and payload retention are separate controls. Tool arguments and results are stored in execution logs by default. The project's **Don't store data** setting stops storage of new call payloads 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.
106 +
107 +For compliance reports and the current sub-processor list, use the [Composio Trust Center](https://trust.composio.dev).