Connector SDK

Companion to: Connectors Marketplace API. Runtime: services/control-plane connector runtime (IConnectorRegistryPort + IConnectorExecutionPort).

A connector is a declarative definition — a JSON/YAML manifest describing operations, auth schemes, HTTP shape, retry/backoff, pagination, and governance hooks. The runtime executes it; you don't ship code. This page is the authoring reference. See the Connectors Marketplace product page.

Definition shape

{
  "name": "salesforce",
  "version": "1.3.0",
  "auth": { "scheme": "oauth2", "token_url": "…", "scopes": ["api"] },
  "operations": {
    "list_opportunities": {
      "method": "GET",
      "path": "/services/data/v60/sobjects/Opportunity",
      "params": { "q": { "in": "query", "required": false } },
      "pagination": { "style": "cursor", "next": "$.nextRecordsUrl" },
      "governance": { "mask": ["pii_email", "financial_account"], "guardian": "gov_crm_v2" }
    }
  },
  "retry": { "attempts": 3, "backoff": "exponential", "base_ms": 250 },
  "timeout_ms": 30000
}

Auth schemes

scheme	Credential stored	Refresh
api_key	{ header | query }: <key>	Manual rotate.
basic	user + pass	Manual rotate.
bearer	token	Manual rotate.
oauth2	refresh_token + token_url + scopes	Auto (runtime schedule).
nhi	Workload-identity / JWT assertion	JIT via NHI Governor.

Pagination styles

• cursor — next is a JSONPath to the next-page URL/token.
• offset — limit / offset increments.
• link — RFC 5988 Link header.

Governance hooks

Every operation may declare:

• mask — detector categories to tokenize on inputs/outputs via the Masking API.
• guardian — the Guardian id that verdicts each call (pre-call verdict gates the third-party request).
• jit_identity — request a just-in-time NHI identity for the call (see NHI Governor).

When guardian or jit_identity is set, the operation must be invoked via the governed …/invoke path (or the virtual MCP server), not the pre-governance …/execute test path.

Publishing

• Org-private: POST /v1/connectors (in the Marketplace API) with the definition — visible only to your org.
• Marketplace: submit the definition for review; once approved it is globally installable and shows in the marketplace catalog.

Errors

Authoring errors surface as 422 validation_error on publish with details pointing at the failing field (operations.list_opportunities.pagination.next: must be a JSONPath string).

---

→ Connectors Marketplace — the product overview. → Connectors Marketplace API — the runtime surface. → Masking API — the mask hook target.