Action Connections

A connection is one tenant's authenticated instance of a provider — the row a step actually dispatches against. This page covers the connection model, how a step picks which connection to use, and the management API you use to create and operate them.

The Connection model

A Connection (domain/connector/connection.go) is always partitioned by TenantID and belongs to a (EnvironmentID, ProviderConfigKey) provider config. The fields that matter to you:

Status lifecycle

ConnectionStatus has five values:

Only active connections resolve; the rest return a typed error at dispatch.

Choosing a connection: direct vs. route

A dispatch request carries a ConnectionMode (domain/connector/connection_mode.go):

• direct (default) — resolve the named ConnectionID.
• route — let the connector routing interceptor select a connection at execution time, returning the chosen one in resolved_connection_id.

Route mode evaluates two mechanisms:

• Connection routes (connection_route.go) — a per-(tenant, provider) ordered fallback chain. Each ConnectionRoute has a Priority and a CELExpression; routes are scanned by priority ASC, created_at ASC, and the first whose CEL is true (or empty, meaning match-all) is the primary, the rest are fallbacks.
• Selection strategies (connection_selection.go) — a pluggable ConnectionSelectionPolicy picks a strategy: priority_chain (default), least_throttled, healthiest, scope_capability_match, region_affinity, cost_aware, weighted_canary, weighted_failover, or sticky_by_entity. Each strategy declares the facts it needs — least_throttled needs the connector_quota fact, scope_capability_match needs oauth_scopes and operation_capabilities, cost_aware needs usage_cost.

The two mechanisms in route mode compose in a fixed order — CEL routes narrow the candidate chain first, then the selection strategy picks within what survived:

The management API

Connector management lives under service ConnectorService (api/proto/api/connector_service.proto), exposed over Connect-RPC and as REST via grpc-gateway under /api/v2/connector/.... The examples below use the REST surface. All requests are tenant-scoped by the caller's auth.

Create a connection

curl -X POST https://your-host/api/v2/connector/connections \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{
    "provider_key": "hubspot",
    "auth_type": "API_KEY",
    "label": "Acme HubSpot (prod)",
    "environment_id": "prod",
    "provider_config_key": "hubspot-main",
    "credentials": { "api_key": "pat-na1-xxxxxxxx" },
    "connection_config": { "region": "na1" },
    "tags": { "env": "prod", "customer_tier": "enterprise" }
  }'

{
  "id": "6f6d1c2e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "tenant_id": "acme",
  "provider_key": "hubspot",
  "environment_id": "prod",
  "provider_config_key": "hubspot-main",
  "auth_type": "API_KEY",
  "label": "Acme HubSpot (prod)",
  "status": "active",
  "connection_config": { "region": "na1" },
  "tags": { "env": "prod", "customer_tier": "enterprise" }
}

# 1. Start — returns an authorize URL, a pending connection, and a CSRF state.
curl -X POST https://your-host/api/v2/connector/oauth/start \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{
    "provider_key": "salesforce",
    "provider_config_key": "sf-main",
    "environment_id": "prod",
    "label": "Acme Salesforce",
    "scopes": ["refresh_token", "api"],
    "connection_config": { "instance": "acme" },
    "tags": { "env": "prod" }
  }'

{
  "authorize_url": "https://login.salesforce.com/services/oauth2/authorize?...",
  "connection_id": "…pending-uuid…",
  "state": "…csrf…"
}

# 2. Callback — exchanges the code and activates the pending connection.
curl -X POST https://your-host/api/v2/connector/oauth/callback \
  -H 'Content-Type: application/json' \
  -d '{ "state": "…csrf…", "code": "…authcode…", "redirect_url": "https://app.example.com/cb" }'

Test, list, update, delete

# Test — actively probes the provider and reports a structured result.
curl -X POST https://your-host/api/v2/connector/connections/{id}/test \
  -H 'Authorization: Bearer <token>'
# → { "ok": true, "tested_at": "...", "error_code": "", "retryable": false, "needs_reconnect": false }

# List — filter by provider, tags, environment, or provider config.
curl 'https://your-host/api/v2/connector/connections?provider_key=hubspot&environment_id=prod' \
  -H 'Authorization: Bearer <token>'

# Update / delete
curl -X PATCH  https://your-host/api/v2/connector/connections/{id} -d '{ "label": "..." }'
curl -X DELETE https://your-host/api/v2/connector/connections/{id}

Execute an action against a connection

curl -X POST https://your-host/api/v2/connector/execute-action \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{
    "action_key": "hubspot.create_contact",
    "connection_id": "6f6d1c2e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
    "connection_mode": "direct",
    "provider_config_key": "hubspot-main",
    "inputs": { "email": "[email protected]", "firstname": "Jane" }
  }'

For route mode, send "connection_id": "", "connection_mode": "route", and a route provider key; the response carries resolved_connection_id. To run the same work durably in the background, POST /api/v2/connector/action-jobs instead (see the async job model in Architecture).

Connect sessions: hosted OAuth for your end users

When you're embedding Ductor and want your end users to link their accounts without your backend proxying secrets, use a connect session (domain/connector/connect_session.go, service ConnectSessionService). You create a short-lived, signed session server-side and hand the user a hosted link:

curl -X POST https://your-host/api/v2/connector/connect-sessions \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "acme",
    "end_user": { "external_id": "user-42", "email": "[email protected]", "organization": "Acme" },
    "allowed_providers": ["hubspot", "salesforce"],
    "policy": { "allowed_scopes": ["contacts.read"], "max_connection_ttl": "86400s" },
    "environment_id": "prod",
    "provider_config_key": "hubspot-main",
    "ttl": "900s"
  }'

{
  "session_id": "…",
  "token": "dct_cs_…",
  "connect_link": "https://connect.your-host/connect/…",
  "expires_at": "2026-07-11T…Z"
}

The token is returned exactly once — storage only holds its SHA-256 hash. The user opens connect_link, which is served by a pre-auth /connect/* router (transport/gateway/connectrouter/) that runs the OAuth flow and creates the connection scoped to the session's allowed_providers and downscoped allowed_scopes. Sessions are one-shot and revocable.

Guided setup

For artifacts that need more than a single credential to be usable — a provider config plus a webhook subscription plus a field mapping — Ductor has a resumable setup flow (domain/connector/setup.go, setupstore/). A ConnectorSetupProfile declares the ordered ConnectorSetupRequirements (authorization, connection config, webhook subscription, mapping profile, permission, readiness check, …), and a ConnectorSetupRun walks a caller through submitting values, validating, and applying them, with readiness gates per surface (action, sync, webhook, workflow, routing, mcp, promotion). The RPCs live under /api/v2/connector/setup/....

Where to go next

• Authentication — how a resolved connection becomes a usable token.
• Triggers & Polling — inbound events from a connection.
• Policies, Quotas & Audit — governing what a connection may reach.