Skip to main content
POST
/
v1
/
connectors
/
{connector_id}
/
connect
Connect Connector
curl --request POST \
  --url https://api.xpander.ai/v1/connectors/{connector_id}/connect \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "version": "<string>",
  "security": {},
  "general_params": [],
  "headers": {},
  "target_system_servers": [],
  "access_scope": "personal",
  "is_service_account": false
}
'
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}
Create a new connection to a connector. For connectors using API keys or tokens, provide credentials directly. For OAuth2 connectors, the response includes a URL to complete browser-based authentication.

​
Path Parameters

​
connector_id
string
required
Unique identifier of the connector

​
Request Body

​
name
string
required
Display name for this connection
​
security
object
Authentication credentials (API keys, tokens, etc.) — structure varies per connector
​
general_params
object
General parameters required by the connector (e.g., base URL, workspace ID)
​
headers
object
Custom HTTP headers to include in connector requests
​
target_system_servers
array
Custom server URLs for on-premise or self-hosted integrations
​
access_scope
string
personal (visible only to creator) or organizational (visible to entire org)
​
is_service_account
boolean
Whether this connection represents a service account

​
Response

Returns the created connection object. For OAuth2 connectors, the response includes:
​
oauth2_required
boolean
true if browser-based OAuth2 authentication is needed
​
message
string
Instructions for completing the OAuth2 flow
​
connector_page_url
string
URL to the xpander.ai platform to complete OAuth2 authentication

​
Example Request

curl -X POST "https://api.xpander.ai/v1/connectors/<connector-id>/connect" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "name": "My Slack Connection",
    "security": {"api_token": "xoxb-..."},
    "access_scope": "organizational"
  }'

​
Notes

  • For OAuth2 connectors, complete the auth flow in the browser using the returned connector_page_url
  • The security object structure varies by connector — check the connector’s documentation
  • Connection owner is automatically set from the API key user if not explicitly provided

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
connector_id
string
required

Body

application/json

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 | null

Pin this connection to a specific connector version. Leave None to use the connector's latest version.

​
security
Security · object

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': {...}}.

​
general_params
GeneralParam · object[] | null

Pre-filled parameters applied to all operations through this connection. Useful for setting common path/query/header params like workspace IDs or API versions.

​
headers
Headers · object

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
Target System Servers · object[] | null

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 | null
default:personal

Who can use this connection. 'personal' (default) restricts to the creating user. 'organizational' makes it available to all org members.

​
is_service_account
boolean | null
default:false

Set to True if this connection uses shared service account credentials rather than personal user credentials. Only meaningful with 'organizational' access scope.

Response

Successful Response