Skip to main content
A connector is an authenticated link to an external system — a CRM, warehouse, enrichment API, or LLM provider. Creating one auto-provisions a dataset that data models source from, and exposes that integration’s actions to your workflows and agents.

​
Define a connector

connectors/hubspot.ts
import { defineConnector, secret } from "@cargo-ai/cdk";

export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
});
The integration slug selects which system to connect; config is a typed, per-integration shape (run cargo-ai cdk types to type it against your workspace). The connector handle carries deferred tokens — hubspot (the handle), hubspot.datasetUuid — that you pass into models and other resources.

​
Secrets vs. config

Use secret() for credentials and env() for non-secret config you want tracked: 
config: { apiKey: secret("PROVIDER_API_KEY") }   // resolved at deploy, never hashed or stored
config: { region: env("PROVIDER_REGION") }        // tracked in the content hash
Always use secret() — never env() — for credentials. secret() resolves at deploy time and is excluded from the content hash and from cargo.state.json. env() bakes the value into the hash, so rotating it reads as drift.
See Secrets & environments for the full secret() vs env() rules and the CARGO_* variables the CLI reads.

​
OAuth and existing connectors

Some integrations authenticate via OAuth in the browser rather than a static key. Adopt an already-connected instance by slug instead of re-creating it:
connectors/openai.ts
import { defineConnector } from "@cargo-ai/cdk";

export const openai = defineConnector("open_ai", {
  integration: "openAi",
  adopt: true,
});
adopt: true links an existing connector (e.g. one authorized through an OAuth flow in the workspace) rather than creating a new one. A later destroy releases adopted connectors instead of deleting them.

​
Using a connector

Once defined, a connector powers three things:
  • Data models source from its dataset — see Models and Extractors.
  • Workflows call its actions via integrations.<slug>.<action>() — see Workflows.
  • Agents invoke its actions via connectorActions — see Agents.
Browse every available integration and its action slugs in the Integrations section, or discover them live with cargo-ai connection integration get <slug> (or generate typed editor autocomplete with cargo-ai cdk types).

​
From the CLI

cargo-ai connection integration list          # available integrations
cargo-ai connection connector list            # your connected instances
cargo-ai connection connector create \
  --name "HubSpot - Prod" --slug hubspot_prod --integration-slug hubspot \
  --config '{ ... }'

​
Using the UI

In the web app, go to Settings → Integrations → Add connection, pick the integration, and complete the auth flow (API key or OAuth). Connectors created in the UI can be adopted into code with adopt: true.

​
Slug rules

Connector slugs are snake_case (my_source) and validated at define time, so a bad slug fails in plan rather than mid-deploy.