API ReferenceConnected Accounts

Create a new connected accountv3.1

POST
/api/v3.1/connected_accounts

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.

Authorization

ApiKeyAuth
x-api-key<token>

Project API key authentication

In: header

Request Body

application/json

auth_configobjectRequired
connectionobjectRequired
validate_credentialsbooleanExperimental

Whether to validate the provided credentials, validates only for API Key Auth scheme

Default: false

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v3.1/connected_accounts" \  -H "Content-Type: application/json" \  -d '{    "auth_config": {      "id": "string"    },    "connection": {}  }'
{  "id": "string",  "connectionData": {    "authScheme": "OAUTH1",    "val": {      "subdomain": "string",      "your-domain": "string",      "region": "string",      "shop": "string",      "account_url": "string",      "COMPANYDOMAIN": "string",      "extension": "string",      "form_api_base_url": "string",      "instanceEndpoint": "string",      "api_url": "string",      "borneo_dashboard_url": "string",      "proxy_username": "string",      "proxy_password": "string",      "domain": "string",      "version": "string",      "dc": "string",      "site_name": "string",      "instanceName": "string",      "account_id": "string",      "your_server": "string",      "server_location": "string",      "base_url": "string",      "status": "INITIALIZING",      "oauth_token": "string",      "authUri": "string",      "oauth_token_secret": "string",      "redirectUrl": "string",      "callbackUrl": "string",      "oauth_verifier": "string",      "consumer_key": "string",      "callback_url": "string",      "error": "string",      "error_description": "string",      "expired_at": "string"    }  },  "status": "INITIALIZING",  "redirect_url": "string",  "redirect_uri": "string",  "experimental": {    "account_type": "PRIVATE",    "acl_config_for_shared": {      "allow_all_users": true,      "allowed_user_ids": [        "string"      ],      "not_allowed_user_ids": [        "string"      ]    }  }}
Edit this page on GitHub