If you’re building an agent, we recommend using sessions instead. See Managing multiple connected accounts for how sessions handle account selection automatically.
List accounts
Retrieve all connected accounts with optional filters:- Python
- TypeScript
- API
Get account details
Retrieve a connected account by ID:- Python
- TypeScript
- API
Get account credentials
Connected-account responses describe the authentication state. Sensitive credential fields inaccount.state.val are redacted by default, for both Composio-managed and custom auth configs. This object is not a source of usable provider tokens for your own tools.
To call a provider API, use Proxy Execute, which injects credentials server-side. For custom business logic, use session extension tools. See Token custody architecture for the boundaries between your application, Composio, and the provider.
Refresh credentials
Manually refresh credentials for a connected account:- Python
- TypeScript
- API
Enable and disable accounts
Change account status without deleting. Set to INACTIVE to pause access, or ACTIVE to restore. Useful for:- Pausing access during subscription lapses
- Temporary disconnection
- Python
- TypeScript
- API
Revoke accounts
To revoke upstream tokens and mark a connectionREVOKED, call composio.connected_accounts.revoke(connected_account_id) in Python or await composio.connectedAccounts.revoke(connectedAccountId) in TypeScript. Upstream token revocation is best effort. The call fails if the toolkit does not support programmatic revocation or the account is not in a revokable state.
Complete deferred OAuth
If your project has an OAuth callback verifier configured, Composio redirects to your verifier with a single-use session URI before activating the connection. Verify the person’s identity in your application, then redeem the URI withcomposio.connected_accounts.complete_auth(user_id=user_id, session_uri=session_uri) in Python or await composio.connectedAccounts.completeAuth({ userId, sessionUri }) in TypeScript.
Composio checks project ownership and the connection’s user ID before completing the token exchange. An expired or already redeemed URI returns a 404.
Delete accounts
Permanently remove a connected account:- Python
- TypeScript
- API
Credential masking
By default, sensitive fields in connected account responses are partially masked for security. This affects fields likeaccess_token, refresh_token, api_key, bearer_token, password, and other secrets.
Instead of returning full values, the API returns the first 4 characters followed by ...:
REDACTED.
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.
If your use case requires calling a provider API directly, use Proxy execute. Composio injects the connected account’s credentials server-side.
Multiple accounts
Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail).- Python
- TypeScript
- API
For session-based apps, see Managing multiple connected accounts for how to pass a specific account to a session.
Execute with a specific account
When you have multiple accounts, specify which one to use withconnected_account_id:
- Python
- TypeScript
- API