Skip to main content
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. 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.

Callback identity verification

Anyone who opens a Connect Link and consents becomes the account attached to that flow. On its own that is exploitable: someone starts a connection under their own user, copies the authorization URL before consenting, and gets a different person to finish it, attaching that person’s provider account under the attacker’s identity. This is OAuth session fixation. Callback identity verification defends against it by confirming the returning user before a connection activates. Set a verifier URL on a project, and Composio holds every OAuth connection there until your server confirms who came back. After the provider callback, Composio redirects the browser to the endpoint you host with one query parameter, session_uri, which carries no connection id, user id, or toolkit name. From your server, authenticating with your project API key, you post the session_uri and the signed-in user_id to the complete auth endpoint. On a match the connection activates and returns its connected_account_id and toolkit_slug; a 200 comes back only once it is ACTIVE. Only a user_id that doesn’t match fails the connection: the request returns 400, and the connection moves to FAILED with its status_reason set to Callback identity verification failed. Any other error leaves the connection pending, so you can restart the flow. The session_uri is single-use and valid for ten minutes; redeeming it spends the session whatever the outcome, so a repeat call returns 404. Your endpoint owns the redirect from here: once you redeem the session, send the user onward yourself. A callback_url set when you create the connection is not used. Turn it on in the dashboard under Settings → General → Configuration. The URL must be public HTTPS, and Composio rejects private and reserved addresses on save, so local development needs a tunnel. Verification is opt-in per project, and once set it covers every OAuth connection in the project that goes through a provider redirect, whether you start it from the API or a Connect Link.
Connections you start from the dashboard can’t complete while a verifier URL is set. A dashboard connection is owned by a Composio dashboard user, which isn’t one of your app’s users and isn’t disclosed to your endpoint, so your app can’t report a matching user_id. Test from your own app, or clear the verifier URL while you work in the dashboard.

List connected accounts with optional filters

Retrieves all connected accounts for your project. Connected accounts represent authenticated user connections to external services (e.g., a user's Gmail account, Slack workspace). Filter by toolkit, status, user ID, or auth config to find specific connections.

Get connected account details by ID

Retrieves comprehensive details of a connected account, including authentication configuration, connection status, and all parameters needed for API requests.

Create a new connected account

Initiates a new connection to an external service for a user. For OAuth-based toolkits, this returns a redirect URL to complete authentication. For API key-based toolkits, provide the credentials directly in the request body. Use the `user_id` field to associate the connection with a specific user in your system. **Deprecated for Composio-managed OAuth:** For Composio-managed auth configs on OAuth1, OAuth2, or DCR_OAUTH schemes, this endpoint is being retired and will start returning `400 BadRequest` on **2026-05-08** for new organizations and **2026-07-03** for all remaining organizations. Migrate those calls to `POST /api/v3/connected_accounts/link`. Custom auth configs and non-OAuth schemes (API key, bearer, basic) continue to be supported here. Responses on the retiring path carry a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) for client-side detection. **Credential check:** where the toolkit supports it, submitted API key, basic, and bearer credentials are checked against the provider before the connection is stored — no opt-in required. For toolkits with the check enabled, credentials the provider rejects fail the request with `ConnectedAccount_CredentialValidationRejected`. If the provider is unreachable, times out, or returns an error of its own, the connection is created as normal.

Re-initiate authentication for a connected account (DEPRECATED)

DEPRECATED: This endpoint re-initiates the authorization flow for a connected account — a developer-triggered reconnection (e.g. to recover a connection whose credentials expired or became invalid), returning a new OAuth redirect URL where applicable. It does NOT perform background credential auto-refresh; the "refresh" name was misleading, which is why the endpoint is deprecated and may be removed in a future release.

Create a new auth link session

Creates a new authentication link session that users can use to connect their accounts

Enable or disable a connected account (DEPRECATED)

DEPRECATED: We are controlling the API surface and the dependencies between endpoints, and enabling or disabling a connected account is covered by existing endpoints. To stop a connected account from being used, delete it with `DELETE /api/v3/connected_accounts/{nanoid}` (pass `?revoke_on_delete=true` to also revoke its upstream credentials); to use the account again, create a new connection. This endpoint still works for existing integrations but may be removed in a future release. It sets the connected account to ACTIVE (`enabled: true`) or INACTIVE (`enabled: false`); inactive accounts cannot be used for API calls. Disabling an account also disables its triggers, and Composio attempts to remove their webhooks at the provider in the background.

Update a connected account

Update a connected account. Supports updating the alias and/or credentials. Only specified fields will be updated. Set a credential field to null to remove it. Alias must be unique within the same project, entity, and toolkit scope.

Delete a connected account

Deletes a connected account. The account immediately stops working for API calls and cannot be restored through the API. Pass `?revoke_on_delete=true` to also revoke the account's upstream credentials.