Usage
Access this class through thecomposio.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 thatuserId 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.
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.
Returns
Promise<ConnectedAccountDeleteResponse> — The deletion response
Example
disable()
Disable a connected account
Returns
Promise<ConnectedAccountUpdateStatusResponse> — Updated connected account details
Example
enable()
Enable a connected account
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.
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 thewaitForConnection 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
Returns
Promise<ConnectionRequest> — Connection request object
Example
link()
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.
Returns
Promise<ConnectedAccountListResponse> — A paginated list of connected accounts
Example
refresh() (deprecated)
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.
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 becomesREVOKED. Revoking an already revoked connection returns an empty revokedTokens list without an upstream call.
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.
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 raisesComposioAclOnlyForSharedError (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.
Returns
Promise<ConnectedAccountPatchResponse> — The PATCH response
Example
updateStatus()
Update the status of a connected account
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.
Returns
Promise<ConnectedAccountRetrieveResponse> — The finalized connected account data
Example