Connected Accounts
A connected account is a single user's authorized connection to a toolkit. It stores their credentials (OAuth tokens or API keys) and links them to your user ID, so your tools can act on that user's behalf.
Composio creates a connected account when a user completes the flow defined by an auth config. From there you manage its full lifecycle:
- Create or link: start a new connection, or generate an auth link session for the user to authorize. See manually authenticating users.
- Refresh: renew authentication for an account whose tokens have expired.
- Enable, disable, or update: change an account's status or metadata without removing it.
- Revoke or delete: revoke the grant at the provider, or remove the account from Composio.
Each account is addressed by its nanoid. List endpoints accept filters so you can find accounts by user, toolkit, or auth config.
Link auth (Composio Connect Links)
A Composio Connect Link is a hosted, secure sign-in page. You create one with the create auth link session endpoint, redirect the user to the returned URL, and Composio handles the rest: the user signs in, Composio creates the connected account, and Composio stores and refreshes its tokens. Credentials never pass through your app. This works for all Composio managed connections, with no OAuth credentials to set up.
By default a connected account is PRIVATE and usable only by its owning user. Mark one SHARED to let other users reach it through a per-connection access control list. See shared connections.
These endpoints use your project API key in the x-api-key header.
Shared-connection ACL fields are experimental and nested under an experimental block on the wire. Pin a specific SDK version if you depend on the current shape.
Endpoints
| Endpoint | Quick Link |
|---|---|
POST /api/v3.1/connected_accounts/{nanoid}/revoke | Revoke a connected account at the provider |
GET /api/v3.1/connected_accounts | List connected accounts with optional filters |
POST /api/v3.1/connected_accounts | Create a new connected account |
GET /api/v3.1/connected_accounts/{nanoid} | Get connected account details by ID |
DELETE /api/v3.1/connected_accounts/{nanoid} | Delete a connected account |
PATCH /api/v3.1/connected_accounts/{nanoid} | Update a connected account |
PATCH /api/v3.1/connected_accounts/{nanoId}/status | Enable or disable a connected account |
POST /api/v3.1/connected_accounts/{nanoid}/refresh | Refresh authentication for a connected account |
POST /api/v3.1/connected_accounts/link | Create a new auth link session |