@zendesk/connector-sdk

[Early Access - Limited Availability]

The Connector SDK provides a framework for building integrations that connect external services to Zendesk Action Builder. A connector acts as a bridge between Zendesk and third-party APIs, enabling users to automate workflows and exchange data seamlessly.

Note: Connector development tools are in early access and currently available only to approved developers. If you're interested in connector development, please visit the waitlist.

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js v24 or later — nodejs.org
• npm (bundled with Node.js) or pnpm — npm install -g pnpm
• Zendesk CLI (zcli) — npm install -g @zendesk/zcli

Verify your installation:

node --version   # v24+
zcli --version

Quick Start

This guide walks you through creating, building, and publishing your first private Zendesk connector.

Step 1: Scaffold a new connector

Use zcli to generate a starter project:

zcli connectors:create my-connector
cd my-connector

This creates a new directory with the connector project structure and installs dependencies.

Step 2: Install the SDK

npm install @zendesk/connector-sdk
# or
pnpm add @zendesk/connector-sdk

Step 3: Define your connector

Open the generated src/index.ts. Every connector is built from three components: a manifest, authentication, and one or more actions.

import { manifest, action, authentication } from '@zendesk/connector-sdk';

Manifest

The manifest is the top-level definition of your connector — its identity, locale, and what it exposes. Only "en" is supported for default_locale at this time.

const connectorManifest = manifest({
  name: 'my-connector',
  title: 'My Connector',
  description: 'A sample connector',
  author: 'Your Name',
  default_locale: 'en',
  version: '1.0.0',
  authentication: auth,
  actions: [sendMessage],
});

export default connectorManifest;

Authentication

Authentication is not where you store real secrets — it defines how credentials are collected from the user and passed to actions at runtime. The inputs you declare here are rendered in the Action Flows UI when a user clicks "Connect". The collected values are securely stored and injected into each action execution.

const auth = authentication({
  type: 'api_key',
  config: {
    api_key: '{{inputs.api_key}}',
    header_name: 'X-Api-Key',
  },
  inputs: [
    {
      name: 'api_key',
      title: 'API Key',
      value_type: 'string',
      control: { type: 'password', max_length: 64 },
      required: true,
      description: 'Your API key for authentication.',
    },
  ],
  allowed_domain: 'api.example.com',
});

Supported authentication types: bearer_token, api_key, basic_authentication, oauth2.

The optional allowed_domain field restricts which domains the HTTP client can reach. It accepts a static string, a template string (e.g. "{{inputs.subdomain}}.example.com"), or a function (params) => string.

Actions

An action represents a single operation your connector can perform. Each action has a unique name (used as an ID), a human-readable title, a description that helps users and LLM agents understand its purpose, plus inputs, output, and an execute function.

Inputs — parameters the user configures when adding the action to a workflow:

const sendMessage = action({
  name: 'send_message',
  title: 'Send Message',
  description: 'Send a message to the service',
  inputs: () => [
    {
      name: 'message',
      title: 'Message',
      description: 'The message content to send.',
      value_type: 'string',
      required: true,
      control: { type: 'text', min_length: 1, max_length: 500 },
    },
  ],

Output — the JSON Schema describing what the action returns. This schema is used by subsequent workflow steps to reference the action's output values:

  output: () => ({
    type: 'object',
    properties: {
      id: { type: 'string' },
      status: { type: 'string' },
    },
  }),

Execute — the function that runs when the action is invoked. It receives the resolved inputs and an authenticated client scoped to the connector's allowed domain:

  execute: ({ inputs, client }) => {
    const resp = client.request({
      url: 'https://api.example.com/messages',
      method: 'POST',
      body: JSON.stringify({ message: inputs.message }),
      headers: { 'content-type': 'application/json' },
    });

    if (!resp.ok) {
      throw new HttpError({ status: resp.status, message: `Request failed: ${resp.body}` });
    }

    return JSON.parse(resp.body);
  },
});

client.request() returns an HttpResponse with status, ok, headers, and body (raw string). Use HttpError to surface structured errors from execute.

Step 4: Build the connector

Bundle your connector for distribution:

zcli connectors:bundle

Use --watch during development to automatically rebuild on file changes:

zcli connectors:bundle --watch

Step 5: Validate and publish

Validate your connector without publishing:

zcli connectors:publish --validationOnly

Once validation passes, publish to your Zendesk account:

zcli connectors:publish

Check the provisioning status after publishing:

zcli connectors:publish-status

To list all private connectors on your account:

zcli connectors:list

A complete working example can be found in the examples/open-weather directory.

API Reference

manifest(definition)

Creates a typed manifest object. Returns the same definition with strict typing applied.

| Field | Type | Description | | ---------------- | ---------------------- | ------------------------------------------------ | | name | string | Unique identifier for the connector (kebab-case) | | title | string | Display name shown in the UI | | description | string | Short description of what the connector does | | author | string | Author name, typically from package.json | | version | string | Connector version (e.g. "1.0.0") | | default_locale | string | Default locale code. Only "en" is supported | | authentication | AuthenticationConfig | Authentication configuration (see below) | | actions | Action[] | Array of actions the connector exposes |

action(definition)

Creates a typed synchronous action. The execute function is called at runtime with the resolved inputs and an authenticated HTTP client.

| Field | Type | Description | | ------------- | --------------------------- | --------------------------------------------- | | name | string | Unique identifier for the action | | title | string | Display name shown in the UI | | description | string | Description of what the action does | | inputs | (params) => ActionField[] | Function returning the action's input fields | | output | (params) => ActionOutput | Function returning the action's output schema | | execute | (params) => any | Function that performs the action logic |

The execute function receives an ExecuteFnParameters object:

| Parameter | Type | Description | | --------- | -------------------- | ------------------------------------------------------------------ | | inputs | InputParameters<T> | Typed map of resolved input values | | client | ZHttp | Authenticated HTTP client scoped to the connector's allowed domain | | context | Context | Optional execution context (workflowId, executionId) |

client.request(options) — Makes an HTTP request. Supported options:

| Field | Type | Description | | --------- | --------------------------------------- | -------------------------------------------------------- | | url | string | Full URL to request | | method | GET \| POST \| PUT \| PATCH \| DELETE | HTTP method | | headers | Record<string, string> | Optional request headers | | body | string | Optional request body (stringify objects before passing) |

Returns an HttpResponse with status, ok, headers, and body (raw string).

client.metadata<T>() — Returns the authenticated connection's metadata, including all resolved authentication input values.

authentication(definition)

Creates a typed authentication configuration. The inputs array defines the fields an admin fills in when creating a connection.

Each input field has:

| Field | Type | Description | | ------------- | ----------------------------------- | ------------------------------------------------------------ | | name | string | Unique key used to reference the value via {{inputs.name}} | | title | string | Display label shown in the UI | | value_type | "string" \| "number" \| "boolean" | Type of the input value | | control | Control | UI control to render (see Control Types below) | | required | boolean | Whether the field must be filled in | | description | string | Optional help text |

Supported authentication types:

| Type | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------- | | bearer_token | Token passed in the Authorization: Bearer header. Requires config.bearer_token | | api_key | Key passed in a custom header. Requires config.api_key and config.header_name | | basic_authentication | HTTP Basic auth. Requires config.username and config.password | | oauth2 | OAuth 2.0 flow. Requires grant_type (authorization_code or client_credentials) and a client configuration |

All types support an optional allowed_domain field to restrict which domains the connector's HTTP client can reach. Accepts a static string, a template string (e.g. "{{inputs.subdomain}}.example.com"), or a function (params) => string.

Control Types

Controls define how an input field is rendered in the UI.

| Control | value_type | Description | | ----------------------------------------- | ----------------------------- | ------------------------------ | | { type: 'text' } | string | Single-line text input | | { type: 'textarea' } | string | Multi-line text input | | { type: 'password' } | string | Masked text input | | { type: 'number' } | number | Numeric input | | { type: 'checkbox' } | boolean | Boolean toggle | | { type: 'dropdown', options: [...] } | string \| number \| boolean | Fixed list of options | | { type: 'multiselect', options: [...] } | array | Multiple selection from a list |

HttpError

Throw an HttpError from execute to signal a failed HTTP interaction with a structured status code and message.

import { HttpError } from '@zendesk/connector-sdk';

throw new HttpError({ status: 404, message: 'Resource not found' });