---
title: "Connect Connector"
method: POST
path: "/v1/tools/connectors/{connector_id}/connect"
tags: ["API v1", "Tools", "Tools Discovery"]
---

# Connect Connector

`POST /v1/tools/connectors/{connector_id}/connect`

## Request

- Base URL: `https://api.xpander.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xpander.ai/v1/tools/connectors/{connector_id}/connect`
- Auth: API key in header `x-api-key`

Create a connection to a connector. For OAuth2 connectors, returns an oauth2_required response with a connector_page_url to complete browser auth.

## Path parameters

- `connector_id` string, required

## Request body

- ConnectConnectorRequest: Request model for creating a new connection to a connector. A connection binds a connector to your organization with specific authentication credentials and settings. The `security` and `headers` fields are write-only — they are accepted on create but never returned in any response for security reasons. For OAuth2 connectors, the API may return an oauth2_required response with a URL to complete browser-based authentication.
  - `name` string, required: Human-readable name for this connection. Must be descriptive enough to distinguish from other connections to the same connector (e.g., 'Production Slack', 'Staging Jira').
  - `version` string, nullable: Pin this connection to a specific connector version. Leave None to use the connector's latest version.
  - `security` object, nullable: Authentication credentials for this connection (WRITE-ONLY; never returned in responses). Structure depends on the connector's auth type: API key auth: {'authMethod': 'apiKey', 'apiKey': '...', 'headerName': 'X-API-Key'}. OAuth2: {'authMethod': 'oauth2', 'oauth2Token': {...}}. A credential slot may carry a reference marker {'$secret_ref': '<vault secret id>'} instead of a literal value; the marker is stored and resolved on read.
  - `general_params` GeneralParam[], nullable: Pre-filled parameters applied to all operations through this connection. Useful for setting common path/query/header params like workspace IDs or API versions.
    - `name` string, required
    - `description` string, required
    - `location` 'path' | 'query' | 'header' | 'cookie', required
    - `value` string, nullable
  - `headers` object, nullable: Custom HTTP headers to include in all API calls through this connection (WRITE-ONLY — never returned in responses). Used for additional authentication or routing headers.
  - `target_system_servers` object[], nullable: Override the connector's default server URLs. Each entry should have a 'url' field and optional 'description'. Use this to point the connection at a different environment (e.g., staging vs production).
  - `access_scope` string, nullable: Who can use this connection. 'personal' (default) restricts to the creating user. 'organizational' makes it available to all org members.
  - `is_service_account` boolean, nullable: Set to True if this connection uses shared service account credentials rather than personal user credentials. Only meaningful with 'organizational' access scope.
  - `owner` string, nullable: User id that owns a personal connection. Set for personal scope; omit (None) for organizational connections.
  - `description` string, nullable: Free-text description for this connection. Defaults to the connector's own description.
  - `per_user` boolean, nullable: Per-user OAuth placeholder: the connection holds no credential of its own and each user signs in individually. At most one per connector per organization.
  - `project_id` string, nullable: The project the connection belongs to; unset means the Default project.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xpander/apis/xpander-ai-api-service.md) - [All operations](https://skmtc.dev/xpander/apis/xpander-ai-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/xpander/apis/xpander-ai-api-service/revisions/4389ec0875d0?raw)