# Create a new auth link session

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

Creates a new authentication link session that users can use to connect their accounts

---

## POST `/api/v3/connected_accounts/link`

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

**Summary:** Create a new auth link session

Creates a new authentication link session that users can use to connect their accounts

### 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_id` (string (authConfigId)) *(required)*: The auth config id to create a link for
- `user_id` (string) *(required)*: The user id to create a link for
- `callback_url` (string): The callback url to create a link for
- `connection_data` (object): Optional data to pre-fill connection fields with default values
  - `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)
  - `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)
  - `state_prefix` (string): The oauth2 state prefix for the connection
  - `long_redirect_url` (boolean): Whether to return the redirect url without shortening
  - `code_verifier` (string)
  - `finalRedirectUri` (string)
  - `webhook_signature` (string)
  - `access_token` (string)
  - `id_token` (string)
  - `token_type` (string)
  - `refresh_token` (string,null)
  - `expires_in` (any)
  - `scope` (any)
  - `authed_user` (object): for slack user scopes
    - `access_token` (string)
    - `scope` (string)
  - `generic_api_key` (string)
  - `api_key` (string)
  - `bearer_token` (string)
  - `basic_encoded` (string)
  - `username` (string)
  - `password` (string)
  - `token` (string)
  - `composio_link_redirect_url` (string)
  - `credentials_json` (string)
  - `sessionId` (string)
  - `devKey` (string)
  - `application_id` (string)
  - `installation_id` (string)
  - `private_key` (string)
  - `client_id` (string): Dynamically registered client ID
  - `client_secret` (string): Dynamically registered client secret
  - `client_id_issued_at` (number)
  - `client_secret_expires_at` (number)
  - `expires_at` (string)

**Example:**

```json
{
  "auth_config_id": "string",
  "user_id": "string",
  "callback_url": "string",
  "connection_data": {
    "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",
    "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",
    "state_prefix": "string",
    "long_redirect_url": true,
    "code_verifier": "string",
    "finalRedirectUri": "string",
    "webhook_signature": "string",
    "access_token": "string",
    "id_token": "string",
    "token_type": "string",
    "refresh_token": null,
    "expires_in": null,
    "scope": null,
    "authed_user": {
      "access_token": "string",
      "scope": "string"
    },
    "generic_api_key": "string",
    "api_key": "string",
    "bearer_token": "string",
    "basic_encoded": "string",
    "username": "string",
    "password": "string",
    "token": "string",
    "composio_link_redirect_url": "string",
    "credentials_json": "string",
    "sessionId": "string",
    "devKey": "string",
    "application_id": "string",
    "installation_id": "string",
    "private_key": "string",
    "client_id": "string",
    "client_secret": "string",
    "client_id_issued_at": 1,
    "client_secret_expires_at": 1,
    "expires_at": "string"
  }
}
```

### Responses

#### 201 - Successfully created auth link

**Response Schema:**

- `link_token` (string) *(required)*: The generated link token for the auth session
- `redirect_url` (string) *(required)*: The redirect URI to send users to for authentication
- `expires_at` (string) *(required)*: ISO timestamp when the link expires
- `connected_account_id` (string (connectedAccountId)) *(required)*: The connected account ID that was created

**Example Response:**

```json
{
  "link_token": "string",
  "redirect_url": "string",
  "expires_at": "string",
  "connected_account_id": "string"
}
```

#### 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 - Auth config 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>)

#### 422 - Unprocessable entity

**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/link" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_config_id": "string",
    "user_id": "string",
    "callback_url": "string",
    "connection_data": {
      "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",
      "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",
      "state_prefix": "string",
      "long_redirect_url": true,
      "code_verifier": "string",
      "finalRedirectUri": "string",
      "webhook_signature": "string",
      "access_token": "string",
      "id_token": "string",
      "token_type": "string",
      "refresh_token": null,
      "expires_in": null,
      "scope": null,
      "authed_user": {
        "access_token": "string",
        "scope": "string"
      },
      "generic_api_key": "string",
      "api_key": "string",
      "bearer_token": "string",
      "basic_encoded": "string",
      "username": "string",
      "password": "string",
      "token": "string",
      "composio_link_redirect_url": "string",
      "credentials_json": "string",
      "sessionId": "string",
      "devKey": "string",
      "application_id": "string",
      "installation_id": "string",
      "private_key": "string",
      "client_id": "string",
      "client_secret": "string",
      "client_id_issued_at": 1,
      "client_secret_expires_at": 1,
      "expires_at": "string"
    }
  }'
```