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>