Connected Accounts

Create a new connected account

Changed on

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.

post/api/v3.1/connected_accounts

Request

  • Base URL
    https://backend.composio.dev
  • URL
    https://backend.composio.dev/api/v3.1/connected_accounts
  • Auth
    API key in header x-api-key

Request body

Response

Successfully created connected account

idstring connectedAccountId required

The id of the connected account

status'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED' required

DEPRECATED: This field will be removed in a future version

redirect_urlstring nullable required

DEPRECATED: This field will be removed in a future version

redirect_uristring nullable required

DEPRECATED: This field will be removed in a future version

Changes

  • 98956f31abf3Revision changes
    • breaking

      added the new required request property //

    • breaking

      added the new required request property //

    • breaking

      the request property // became not nullable

    • breaking

      removed subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 subschema #6 subschema #7 subschema #8 subschema #9 subschema #10 subschema #11 subschema #12 subschema #13 subschema #14 from the / request property oneOf list

    • breaking

      the / request property type changed from no type to object

    • breaking

      the response's property type changed from no type to object for status

    • warning

      removed the request property

    • info

      api operation id postV3_1ConnectedAccounts removed and replaced with postConnectedAccounts

    • info

      added the non-success response with the status

    • info

      removed subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 subschema #6 subschema #7 subschema #8 subschema #9 subschema #10 subschema #11 subschema #12 subschema #13 subschema #14 from the response property oneOf list for the response status

    • info

      added the required property / to the response with the status

    • info

      added the required property / to the response with the status

  • 1d3aac1128efRevision changes
    • warning

      removed the optional property from the response with the status