@zendesk/connector-sdk

@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' });