@devries-cameron20 / composio-1 / commits / f66e9ad2c
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: explain user IDs and reconnecting accounts for sessions (DEVREL-192) (#5374)

> Written by an AI agent on behalf of @olearycrew, following their spec. @olearycrew has not reviewed it yet. ## Summary Customers connect or reconnect an account in the dashboard, see it as active, and then a Tool Router session created with their app's `user_id` can't use it. The docs didn't explain that sessions match accounts by project and `user_id`, how to find which user owns an account, or how to reconnect under the right user. Modem's brief has 13 asks on this across two topics (5 about setting the user ID when recreating accounts, 8 about a custom auth config that Tool Router doesn't discover). Linear: [DEVREL-192](https://linear.app/composio/issue/DEVREL-192/docs-explain-user-ids-and-reconnecting-accounts-for-tool-router) Designated PR reviewer: [@jkomyno](mailto:alberto@composio.dev). ## Changes - New page `docs/content/docs/authentication/session-cant-find-account.mdx`, added to the Authentication nav after "Managing multiple connected accounts". Every example has Python, TypeScript and cURL tabs. It covers: - How project, auth config, connected account and session relate. - Looking up an account by its `ca_...` ID to read its `user_id`. The TypeScript tab uses the raw client (`composio.getClient().connectedAccounts.retrieve()`), because `connectedAccounts.get()` and `list()` don't return `userId`. - A checklist: status, toolkit restrictions, the session's `authConfigs`, `is_enabled_for_tool_router`, and pinned `connectedAccounts`. - A reconnect recipe: create a session for the intended user, authorize, wait, then confirm with `session.toolkits(is_connected=True)`. A note says to send the link only to the person who owns that user ID. - A one-line link to the page from `auth-configuration/connected-accounts.mdx` and from the account-selection section of `configuring-sessions.mdx`. ## Type of change - [ ] Bug fix - [ ] New feature - [ ] Refactor/Chore - [x] Documentation - [ ] Breaking change ## How Has This Been Tested? Not built or linted locally (the machine is shared, so no `bun install` and no `next build`). CI's docs checks are the first real run, including the Twoslash and snippet checks on the new TypeScript and Python blocks. I checked each product claim against this repo before writing it: | Claim on the page | Source | |---|---| | Retrieving an account returns `user_id` | `docs/public/openapi-v3.json` (`GET /api/v3/connected_accounts/{nanoid}`); `GetApiV31ConnectedAccountsByNanoidResponses` in `@composio/client` 2.1.17 types `user_id: string`; Python `connected_accounts.get` is the raw `retrieve` | | You can't change an existing account's `user_id` | `PatchConnectedAccountBody` only has `alias`, `connection`, `experimental` | | `composio dev init` writes `pg-test-<member id>` to `COMPOSIO_TEST_USER_ID` | `ts/packages/cli/src/commands/init.cmd.ts:157`, registered under `dev` in `ts/packages/cli/src/commands/dev.cmd.ts:44` | | `authConfigs.update` / `auth_configs.update` forward `is_enabled_for_tool_router` | `ts/packages/core/src/models/AuthConfigs.ts:234-262`, `python/composio/core/models/auth_configs.py:81-104` | | Configs that sessions create get the flag automatically, and configs you create yourself need it | Existing wording on `extending-sessions/custom-mcp.mdx` (commits 83c5346f0, 6b9f1fd9a) | | A pinned `connectedAccounts` entry never falls back | `docs/content/kb/guide/mcp-tool-router-sessions.mdx` | I couldn't verify which `user_id` the dashboard's Connect action uses, so the page only says accounts connected "outside your app, such as from the dashboard" may use a different user ID, and names the CLI's `pg-test-` user as the confirmed example. Brendan approved that wording. ## Checklist - [ ] I have read the Code of Conduct and this PR adheres to it - [ ] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the [third-party links policy](https://github.com/ComposioHQ/composio/blob/next/CONTRIBUTING.md#third-party-links-in-docs) - [ ] I ran linters/tests locally and they passed - [x] I updated documentation as needed - [ ] I added tests or explain why not applicable - [ ] I added a changeset if this change affects published packages ## Additional context ELI5: Composio keeps each person's app logins in a drawer labeled with their user ID. If someone files a login under the wrong label, your agent opens the right drawer and finds it empty. This page shows how to read the labels and file a fresh login in the right drawer. --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Brendan O'Leary committed Nov 13, 2026 at 11:16 UTC f66e9ad2cc606b7a2cf49fba33ff3c9e7b58b5af
4 files changed +167
docs/content/docs/auth-configuration/connected-accounts.mdx
+2
@@ -12,6 +12,8 @@ If you're building an agent, we recommend using [sessions](/docs/configuring-ses
12
13 Connected accounts are authenticated connections between your users and toolkits. After users authenticate (see [Authenticating tools](/docs/tools-direct/authenticating-tools)), you can manage these accounts throughout their lifecycle.
14
15 +If an account is active but a session can't use it, see [When a session can't find a connected account](/docs/authentication/session-cant-find-account).
16 +
17 Composio automatically handles token refresh and credential management. This guide covers manual operations: listing, retrieving, refreshing, enabling, disabling, and deleting accounts.
18
19 ## List accounts
docs/content/docs/authentication/meta.json
+1
@@ -4,6 +4,7 @@
4 "managed-auth-for-custom-tools",
5 "manually-authenticating",
6 "managing-multiple-connected-accounts",
7 + "session-cant-find-account",
8 "importing-existing-connections",
9 "programmatic-auth-configs",
10 "controlling-scopes",
docs/content/docs/authentication/session-cant-find-account.mdx new
+162
@@ -0,0 +1,162 @@
1 +---
2 +title: When a session can't find a connected account
3 +description: Diagnose user ID, status, and auth config mismatches, then reconnect the account under the right user
4 +keywords: [user id, user_id, reconnect, connected account not found, NoActiveConnection, is_enabled_for_tool_router, dashboard, playground]
5 +---
6 +
7 +A session only sees connected accounts that match its project and its `user_id`. An account can show as active in the dashboard and still be invisible to your session if it was created under a different user ID or auth config.
8 +
9 +## How the pieces fit
10 +
11 +- **Project.** Your API key picks the project. Auth configs, connected accounts, and sessions never cross projects.
12 +- **Auth config.** How a toolkit authenticates: Composio managed auth or your own credentials. See [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app).
13 +- **Connected account.** One user's credentials for one auth config. Each account stores the `user_id` it was created for.
14 +- **Session.** Created for one `user_id`. At execution time it picks an `ACTIVE` account that belongs to that user, unless you pin one with [`connectedAccounts`](/docs/configuring-sessions#account-selection).
15 +
16 +Use your application's own stable user ID everywhere: when you create sessions and when you connect accounts. See [userID best practices](/docs/how-composio-works#users).
17 +
18 +## Find the user ID that owns the account
19 +
20 +Look up the account by its ID (`ca_...`, shown in the dashboard) and read its `user_id`:
21 +
22 +<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
23 +<Tab value="Python">
24 +```python
25 +account = composio.connected_accounts.get("ca_123")
26 +
27 +print(account.user_id, account.status, account.auth_config.id)
28 +```
29 +</Tab>
30 +<Tab value="TypeScript">
31 +```typescript
32 +import { Composio } from '@composio/core';
33 +const composio = new Composio({ apiKey: 'your_api_key' });
34 +// ---cut---
35 +// connectedAccounts.get() doesn't return user_id, so use the raw API client
36 +const account = await composio.getClient().connectedAccounts.retrieve('ca_123');
37 +
38 +console.log(account.user_id, account.status, account.auth_config.id);
39 +```
40 +</Tab>
41 +<Tab value="API">
42 +```bash
43 +curl -s https://backend.composio.dev/api/v3.1/connected_accounts/ca_123 \
44 + -H "x-api-key: $COMPOSIO_API_KEY" \
45 + | jq '{user_id, status, auth_config: .auth_config.id}'
46 +```
47 +</Tab>
48 +</Tabs>
49 +
50 +If the `user_id` isn't the one your session uses, the session won't find the account. This happens most often with accounts connected outside your app, such as from the dashboard or a developer tool. For example, `composio dev init` writes a playground test user (`pg-test-<your member ID>`) to `COMPOSIO_TEST_USER_ID`, which is not one of your application's users.
51 +
52 +You can't change the `user_id` of an existing connected account. [Reconnect it](#reconnect-under-the-right-user) under the right user instead.
53 +
54 +## Check the rest of the match
55 +
56 +If the user ID matches and the session still can't use the account, check these in order:
57 +
58 +1. **Status.** The account must be `ACTIVE` and not disabled. `INITIATED` means the user never finished the flow. `EXPIRED` means it needs a new grant. See [connection status](/docs/authentication#connection-lifecycle).
59 +2. **Toolkit restrictions.** If the session sets `toolkits`, the toolkit must be allowed. Toolkit restrictions apply before account lookup.
60 +3. **Auth config.** If the session passes [`authConfigs`](/docs/configuring-sessions#custom-auth-configs) for the toolkit, the account must belong to that auth config.
61 +4. **Tool Router flag.** Auth configs that sessions create are enabled for Tool Router automatically. If you created the auth config yourself, in the dashboard or the API, set `is_enabled_for_tool_router` to `true` so sessions can match its accounts by `user_id`.
62 +5. **Pinned account.** If the session passes `connectedAccounts` for the toolkit, it uses exactly that account and never falls back to another one. Update the session or create a new one to change it.
63 +
64 +Enable the Tool Router flag on an auth config you created:
65 +
66 +<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
67 +<Tab value="Python">
68 +```python
69 +composio.auth_configs.update(
70 + "ac_your_config",
71 + options={"type": "custom", "is_enabled_for_tool_router": True},
72 +)
73 +```
74 +</Tab>
75 +<Tab value="TypeScript">
76 +```typescript
77 +import { Composio } from '@composio/core';
78 +const composio = new Composio({ apiKey: 'your_api_key' });
79 +// ---cut---
80 +await composio.authConfigs.update('ac_your_config', {
81 + type: 'custom',
82 + isEnabledForToolRouter: true,
83 +});
84 +```
85 +</Tab>
86 +<Tab value="API">
87 +```bash
88 +curl -X PATCH https://backend.composio.dev/api/v3.1/auth_configs/ac_your_config \
89 + -H "x-api-key: $COMPOSIO_API_KEY" \
90 + -H "Content-Type: application/json" \
91 + -d '{"type": "custom", "is_enabled_for_tool_router": true}'
92 +```
93 +</Tab>
94 +</Tabs>
95 +
96 +## Reconnect under the right user
97 +
98 +Create a session for your application's user ID, then authorize the toolkit from that session. The new connected account belongs to that user, so this session and later sessions for the same user can use it. Pass `authConfigs` if the toolkit uses your own auth config.
99 +
100 +<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
101 +<Tab value="Python">
102 +```python
103 +session = composio.create(
104 + user_id="user_123",
105 + auth_configs={"gmail": "ac_your_config"},
106 +)
107 +
108 +connection_request = session.authorize("gmail")
109 +print(connection_request.redirect_url) # Send the user here
110 +
111 +connection_request.wait_for_connection(60)
112 +
113 +# Confirm the session sees the account
114 +for toolkit in session.toolkits(is_connected=True).items:
115 + account = toolkit.connection and toolkit.connection.connected_account
116 + print(toolkit.slug, account.id if account else None)
117 +```
118 +</Tab>
119 +<Tab value="TypeScript">
120 +```typescript
121 +import { Composio } from '@composio/core';
122 +const composio = new Composio({ apiKey: 'your_api_key' });
123 +// ---cut---
124 +const session = await composio.create('user_123', {
125 + authConfigs: { gmail: 'ac_your_config' },
126 +});
127 +
128 +const connectionRequest = await session.authorize('gmail');
129 +console.log(connectionRequest.redirectUrl); // Send the user here
130 +
131 +await connectionRequest.waitForConnection(60000);
132 +
133 +// Confirm the session sees the account
134 +const connected = await session.toolkits({ isConnected: true });
135 +connected.items.forEach((toolkit) => {
136 + console.log(toolkit.slug, toolkit.connection?.connectedAccount?.id);
137 +});
138 +```
139 +</Tab>
140 +<Tab value="API">
141 +```bash
142 +SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
143 + -H "x-api-key: $COMPOSIO_API_KEY" \
144 + -H "Content-Type: application/json" \
145 + -d '{"user_id": "user_123", "auth_configs": {"gmail": "ac_your_config"}}' | jq -r '.session_id')
146 +
147 +# Send the user to redirect_url
148 +curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \
149 + -H "x-api-key: $COMPOSIO_API_KEY" \
150 + -H "Content-Type: application/json" \
151 + -d '{"toolkit": "gmail"}' | jq -r '.redirect_url'
152 +
153 +# After the user finishes, confirm the session sees the account
154 +curl -s "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits?is_connected=true" \
155 + -H "x-api-key: $COMPOSIO_API_KEY"
156 +```
157 +</Tab>
158 +</Tabs>
159 +
160 +Only send the Connect Link to the person who owns that user ID. Whoever completes the flow decides which external account gets attached to `user_123`.
161 +
162 +Once the new account is active, delete or disable the old one under the wrong user ID if nobody needs it. See [Connected accounts](/docs/auth-configuration/connected-accounts#delete-accounts).
docs/content/docs/configuring-sessions.mdx
+2
@@ -824,6 +824,8 @@ When executing a tool, the session selects the connected account in this order:
824
825 When a user has multiple connected accounts for a toolkit, the session uses the most recently connected one.
826
827 +If an account exists but the session doesn't use it, see [When a session can't find a connected account](/docs/authentication/session-cant-find-account).
828 +
829 ## Disabling the sandbox
830
831 By default, sessions include the [sandbox](/docs/sandbox/remote), a persistent environment that provides `COMPOSIO_REMOTE_WORKBENCH` and `COMPOSIO_REMOTE_BASH_TOOL`. If your use case doesn't need code execution, disable it: