# Create a new connected account

**Documentation:** /reference/api-reference/connected-accounts/postConnectedAccounts

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.

---

## POST `/api/v3/connected_accounts`

**Endpoint:** `https://backend.composio.dev/api/v3/connected_accounts`

**Summary:** 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.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Request Body

**Schema:**

- `auth_config` (object) *(required)*
  - `id` (string (authConfigId)) *(required)*: The auth config id of the app (must be a valid auth config id)
- `connection` (object) *(required)*
  - `state` (object): The state of the connected account
    - `authScheme` (enum: "OAUTH1" | "OAUTH2" | "API_KEY" | ...) *(required)*
    - `val` (object) *(required)*
      - `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` (enum: "INITIALIZING" | "INITIATED" | "ACTIVE" | ...) *(required)*
      - `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)
  - `data` (object): DEPRECATED: This parameter will be removed in a future version. Please use state instead.
    - `[key: string]` (any)
  - `user_id` (string): The user id of the connected account
  - `callback_url` (string (uri)): The URL to redirect to after connection completion
  - `redirect_uri` (string (uri)): DEPRECATED: This parameter will be removed in a future version. Please use callback_url instead.
  - `deprecated_is_v1_rerouted` (boolean): DEPRECATED: This parameter will be removed in a future version.
- `validate_credentials` (boolean): [EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme

**Example:**

```json
{
  "auth_config": {
    "id": "string"
  },
  "connection": {
    "state": {
      "authScheme": "OAUTH1",
      "val": {
        "subdomain": "...",
        "your-domain": "...",
        "region": "...",
        "shop": "...",
        "account_url": "...",
        "COMPANYDOMAIN": "...",
        "extension": "...",
        "form_api_base_url": "...",
        "instanceEndpoint": "...",
        "api_url": "...",
        "borneo_dashboard_url": "...",
        "proxy_username": "...",
        "proxy_password": "...",
        "domain": "...",
        "version": "...",
        "dc": "...",
        "site_name": "...",
        "instanceName": "...",
        "account_id": "...",
        "your_server": "...",
        "server_location": "...",
        "base_url": "...",
        "status": "...",
        "oauth_token": "...",
        "authUri": "...",
        "oauth_token_secret": "...",
        "redirectUrl": "...",
        "callbackUrl": "...",
        "oauth_verifier": "...",
        "consumer_key": "...",
        "callback_url": "...",
        "error": "...",
        "error_description": "...",
        "expired_at": "..."
      }
    },
    "data": {
      "key": null
    },
    "user_id": "default",
    "callback_url": "https://example.com",
    "redirect_uri": "https://example.com",
    "deprecated_is_v1_rerouted": false
  },
  "validate_credentials": false
}
```

### Responses

#### 201 - Successfully created connected account

**Response Schema:**

- `id` (string (connectedAccountId)) *(required)*: The id of the connected account
- `connectionData` (object) *(required)*: The connection data of the connected account
  - `authScheme` (enum: "OAUTH1" | "OAUTH2" | "API_KEY" | ...) *(required)*
  - `val` (object) *(required)*
    - `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` (enum: "INITIALIZING" | "INITIATED" | "ACTIVE" | ...) *(required)*
    - `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` (enum: "INITIALIZING" | "INITIATED" | "ACTIVE" | ...) *(required)*: DEPRECATED: This field will be removed in a future version
- `redirect_url` (string,null) *(required)*: DEPRECATED: This field will be removed in a future version
- `redirect_uri` (string,null) *(required)*: DEPRECATED: This field will be removed in a future version
- `deprecated` (object) *(required)*: DEPRECATED: This field will be removed in a future version. Please use id and auth_config.id instead.
  - `uuid` (string (uuid)) *(required)*: The uuid of the connected account
  - `authConfigUuid` (string (uuid)) *(required)*: The uuid of the auth config

**Example Response:**

```json
{
  "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": null,
  "redirect_uri": null,
  "deprecated": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "authConfigUuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

#### 400 - Bad request

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Not found

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 501 - Not implemented

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X POST "https://backend.composio.dev/api/v3/connected_accounts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_config": {
      "id": "string"
    },
    "connection": {
      "state": {
        "authScheme": "OAUTH1",
        "val": {
          "subdomain": "...",
          "your-domain": "...",
          "region": "...",
          "shop": "...",
          "account_url": "...",
          "COMPANYDOMAIN": "...",
          "extension": "...",
          "form_api_base_url": "...",
          "instanceEndpoint": "...",
          "api_url": "...",
          "borneo_dashboard_url": "...",
          "proxy_username": "...",
          "proxy_password": "...",
          "domain": "...",
          "version": "...",
          "dc": "...",
          "site_name": "...",
          "instanceName": "...",
          "account_id": "...",
          "your_server": "...",
          "server_location": "...",
          "base_url": "...",
          "status": "...",
          "oauth_token": "...",
          "authUri": "...",
          "oauth_token_secret": "...",
          "redirectUrl": "...",
          "callbackUrl": "...",
          "oauth_verifier": "...",
          "consumer_key": "...",
          "callback_url": "...",
          "error": "...",
          "error_description": "...",
          "expired_at": "..."
        }
      },
      "data": {
        "key": null
      },
      "user_id": "default",
      "callback_url": "https://example.com",
      "redirect_uri": "https://example.com",
      "deprecated_is_v1_rerouted": false
    },
    "validate_credentials": false
  }'
```