Connectors

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. An adopted connector is read-only: deploys never push name, config, rateLimit or cacheTtlMilliseconds to it, so the credentials authorized outside the repo are never overwritten. A later destroy releases it instead of deleting it.Aside from unified models — which Cargo generates and the CDK can only bind to, never create — this is the only implicit link the CDK makes. Every other resource is created outright: if one with the same slug or name already exists, the deploy fails rather than adopting it. To bring an existing workspace resource under code, use cargo-ai cdk pull, or cargo-ai cdk import <id> <uuid> to bind one resource explicitly.

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 uses.<key>.<action>() (declared in uses) — see Workflows.
Agents invoke its actions by referencing connector.actions.<slug> in their uses — 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.

Get started

Resources

Deploy

CLI

Skills

Reference

Define a connector

Secrets vs. config

OAuth and existing connectors

Using a connector

From the CLI

Using the UI

Slug rules

​Define a connector

​Secrets vs. config

​OAuth and existing connectors

​Using a connector

​From the CLI

​Using the UI

​Slug rules

Define a connector

Secrets vs. config

OAuth and existing connectors

Using a connector

From the CLI

Using the UI

Slug rules