Skip to main content

Usage

Access this class through the composio.connectedAccounts property:

Methods

completeAuth()

Complete a deferred OAuth connection once you have verified the user’s identity. When your project has an OAuth callback verifier configured, Composio does not activate a new OAuth connection by itself: it redirects to your verifier with a single-use session URI. After confirming who the user is, redeem that session URI here; Composio checks that your project owns the pending connection and that userId is its owner, completes the token exchange, and the connection becomes ACTIVE. The session URI is single-use: redeeming it twice, or after it expires, fails with a 404 from the API.
Parameters Returns Promise<ConnectedAccountCompleteAuthResponse> — The completed connection’s ID and toolkit Example

delete()

Deletes a connected account. This method permanently removes a connected account from the Composio platform. This action cannot be undone and will revoke any access tokens associated with the account.
Parameters Returns Promise<ConnectedAccountDeleteResponse> — The deletion response Example

disable()

Disable a connected account
Parameters Returns Promise<ConnectedAccountUpdateStatusResponse> — Updated connected account details Example

enable()

Enable a connected account
Parameters Returns Promise<ConnectedAccountUpdateStatusResponse> — Updated connected account details Example

get()

Retrieves a specific connected account by its ID. This method fetches detailed information about a single connected account and transforms the response to the SDK’s standardized format.
Parameters Returns Promise<ConnectedAccountRetrieveResponse> — The connected account details Example

initiate()

Compound function to create a new connected account. This function creates a new connected account and returns a connection request. Users can then wait for the connection to be established using the waitForConnection method. Deprecated for Composio-managed OAuth (OAuth1, OAuth2, DCR_OAUTH). The legacy POST /api/v3/connected_accounts endpoint that this method wraps is being retired for Composio-managed auth configs on redirectable schemes. The cutover is 2026-05-08 for new organizations and 2026-07-03 for all remaining organizations. After your org’s cutover, this method will throw ComposioLegacyConnectedAccountsEndpointRetiredError for that specific combination. Use ConnectedAccounts.link for Composio-managed OAuth — it works for every redirectable scheme regardless of whether the auth config is Composio-managed or custom, and the return shape is the same. Custom auth configs (your own OAuth app) and non-OAuth schemes (API key, bearer token, basic auth) are unaffected and continue to work on initiate(). See /docs/changelog/2026/04/24
Parameters Returns Promise<ConnectionRequest> — Connection request object Example

Parameters Returns Promise<ConnectionRequest> — Connection request object Example

list()

Lists all connected accounts based on provided filter criteria. This method retrieves connected accounts from the Composio API with optional filtering.
Parameters Returns Promise<ConnectedAccountListResponse> — A paginated list of connected accounts Example

refresh() (deprecated)

DeprecatedThe POST /connected_accounts/\{id\}/refresh endpoint is deprecated by the Composio API. Re-initiate authentication instead: composio.connectedAccounts.link(userId, authConfigId) for a fresh connection, or session.authorize(toolkit) from a session. Behaviour is unchanged while the endpoint remains available; do not generate new code against refresh.
Refreshes a connected account’s authentication credentials. This method attempts to refresh OAuth tokens or other credentials associated with the connected account. This is useful when a token has expired or is about to expire.
Parameters Returns Promise<ConnectedAccountRefreshResponse> — The response containing the refreshed account details Example

revoke()

Revoke a connected account at the upstream provider. Best-effort upstream revocation of the stored tokens/credentials; on success the connection status becomes REVOKED. Revoking an already revoked connection returns an empty revokedTokens list without an upstream call.
Parameters Returns Promise<ConnectedAccountRevokeResponse> — Which tokens were revoked and the resulting status Example

update()

Enable or disable a connected account. Accepts { enabled: boolean }. Use updateAcl() for ACL writes on SHARED connections.
Parameters Returns Promise<ConnectedAccountUpdateStatusResponse> — The update response Example

updateAcl()

Update the per-user ACL on a SHARED connected account. Experimental — shape may change in future releases. Only meaningful for SHARED connections — calling this on a PRIVATE connection raises ComposioAclOnlyForSharedError (400). ACL writes require the connection’s creator or an API key. PATCH semantics: omit a field to leave it unchanged; pass an empty array to clear an allow/deny list. At least one field must be provided.
Parameters Returns Promise<ConnectedAccountPatchResponse> — The PATCH response Example

updateStatus()

Update the status of a connected account
Parameters Returns Promise<ConnectedAccountUpdateStatusResponse> — Updated connected account details Example

waitForConnection()

Waits for a connection request to complete and become active. This method continuously polls the Composio API to check the status of a connection until it either becomes active, enters a terminal error state, or times out.
Parameters Returns Promise<ConnectedAccountRetrieveResponse> — The finalized connected account data Example