> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agentkit`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Zendesk

**Authentication:** API KEY
**Categories:** Customer Support
## What you can do

Connect this agent connector to let your agent:

- **Get side conversation, user, ticket** — Retrieve a specific side conversation on a Zendesk ticket by its ID
- **List side conversations, tickets, views** — List all side conversations on a Zendesk ticket
- **Update ticket** — Update an existing Zendesk ticket
- **Reply ticket** — Add a public reply or internal note to a Zendesk ticket
- **Search search** — Search Zendesk tickets using a query string
- **Create user, ticket** — Create a new user in Zendesk

## Authentication

This connector uses **API KEY** authentication.

Before calling this connector from your code, create the Zendesk connection in **AgentKit** > **Connections** and copy the exact **Connection name** from that connection into your code. The value in code must match the dashboard exactly.

## Set up the connector

Register your Zendesk API credentials with Scalekit so it can authenticate requests on your behalf. You'll need your Zendesk subdomain, email address, and an API token from your Zendesk Admin Center.

1. ### Generate an API token

    - In your Zendesk Admin Center, go to **Apps and integrations** → **APIs** → **Zendesk API**.

    - Under **Settings**, enable **Token access**.

      > Image: Zendesk API configuration page with Allow API token access enabled

    - Click **Add API token**, enter a description, and click **Create**.

    - Copy the token — it is only shown once.

2. ### Create a connection

    In [Scalekit dashboard](https://app.scalekit.com), go to **AgentKit** > **Connections** > **Create Connection**. Find **Zendesk** and click **Create**.

3. ### Create a connected account

    Go to **Connected Accounts** for your Zendesk connection and click **Add account**. Fill in the required fields:

    - **Your User's ID** — a unique identifier for the user in your system
    - **Zendesk Domain** — your full Zendesk domain (e.g., `yourcompany.zendesk.com`)
    - **Email Address** — the Zendesk account email address
    - **API Token** — the token you copied in step 1

    - Click **Save**.

      > Image: Add connected account form for Zendesk in Scalekit dashboard

## Code examples

Connect a user's Zendesk account and make API calls on their behalf — Scalekit handles OAuth and token management automatically.

**Don't worry about your Zendesk domain in the path.** Scalekit automatically resolves `{{domain}}` from the connected account's configuration. For example, a request with `path="/v2/users/me"` will be sent to `https://mycompany.zendesk.com/api/v2/users/me` automatically.

## Proxy API Calls

  ### Node.js

```typescript

const connectionName = 'zendesk'; // get your connection name from connection configurations
const identifier = 'user_123';  // your unique user identifier

// Get your credentials from app.scalekit.com → Developers → Settings → API Credentials
const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENV_URL,
  process.env.SCALEKIT_CLIENT_ID,
  process.env.SCALEKIT_CLIENT_SECRET
);
const actions = scalekit.actions;

// Authenticate the user
const { link } = await actions.getAuthorizationLink({
  connectionName,
  identifier,
});
console.log('🔗 Authorize Zendesk:', link); // present this link to your user for authorization, or click it yourself for testing
process.stdout.write('Press Enter after authorizing...');
await new Promise(r => process.stdin.once('data', r));

// Make a request via Scalekit proxy
const result = await actions.request({
  connectionName,
  identifier,
  path: '/v2/users/me',
  method: 'GET',
});
console.log(result);
```

  ### Python

```python

from dotenv import load_dotenv
load_dotenv()

connection_name = "zendesk"  # get your connection name from connection configurations
identifier = "user_123"      # your unique user identifier

# Get your credentials from app.scalekit.com → Developers → Settings → API Credentials
scalekit_client = scalekit.client.ScalekitClient(
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
    env_url=os.getenv("SCALEKIT_ENV_URL"),
)
actions = scalekit_client.actions

# Authenticate the user
link_response = actions.get_authorization_link(
    connection_name=connection_name,
    identifier=identifier
)
# present this link to your user for authorization, or click it yourself for testing
print("🔗 Authorize Zendesk:", link_response.link)
input("Press Enter after authorizing...")

# Make a request via Scalekit proxy
result = actions.request(
    connection_name=connection_name,
    identifier=identifier,
    path="/v2/users/me",
    method="GET"
)
print(result)
```

## Tool list

Use the exact tool names from the **Tool list** below when you call `execute_tool`. If you're not sure which name to use, list the tools available for the current user first.

## Tool list

### `zendesk_groups_list`

List all groups in Zendesk. Groups are used to organize agents and route tickets.

Parameters:

- `page` (`number`, optional): Page number for pagination
- `per_page` (`number`, optional): Number of groups per page (max 100)

### `zendesk_organization_get`

Retrieve details of a specific Zendesk organization by ID. Returns organization name, domain names, tags, notes, shared ticket settings, and custom fields.

Parameters:

- `organization_id` (`number`, required): The ID of the organization to retrieve
- `include` (`string`, optional): Additional related data to include (e.g., lookup_relationship_fields)

### `zendesk_organizations_list`

List all organizations in Zendesk with pagination support.

Parameters:

- `page` (`number`, optional): Page number for pagination
- `per_page` (`number`, optional): Number of organizations per page (max 100)

### `zendesk_search_tickets`

Search Zendesk tickets using a query string. Supports Zendesk's search syntax (e.g., 'type:ticket status:open'). Zendesk limits search results to 1,000 total — the maximum valid page is floor(1000 / per_page) (e.g., per_page=100 → max page 10, per_page=25 → max page 40). Stop paginating when next_page is null or you reach the max page; requesting beyond the limit returns a 400 error.

Parameters:

- `query` (`string`, required): Search query string using Zendesk search syntax (e.g., 'type:ticket status:open assignee:me')
- `page` (`number`, optional): Page number for pagination. Max valid page = floor(1000 / per_page). Do not exceed this — Zendesk returns a 400 error beyond the 1,000 result limit.
- `per_page` (`number`, optional): Number of results per page (max 100). Determines the max page ceiling: floor(1000 / per_page). Higher values mean fewer pages but a lower max page number.
- `sort_by` (`string`, optional): Field to sort results by (updated_at, created_at, priority, status, ticket_type)
- `sort_order` (`string`, optional): Sort direction: asc or desc (default: desc)

### `zendesk_side_conversation_get`

Retrieve a specific side conversation on a Zendesk ticket by its ID. Returns the side conversation's state, subject, participants, preview text, and timestamps. Requires the Collaboration add-on.

Parameters:

- `side_conversation_id` (`string`, required): The ID of the side conversation to retrieve
- `ticket_id` (`number`, required): The ID of the parent ticket
- `include` (`string`, optional): Sideloads to include alongside the response. Use 'side_conversation_events' to include the full event history of the side conversation.

### `zendesk_side_conversations_list`

List all side conversations on a Zendesk ticket. Returns side conversations including their state, subject, participants, and preview text. Requires the Collaboration add-on.

Parameters:

- `ticket_id` (`number`, required): The ID of the ticket whose side conversations to list
- `include` (`string`, optional): Sideloads to include alongside the response. Use 'side_conversation_events' to include the full event history for each side conversation.

### `zendesk_ticket_comments_list`

Retrieve all comments (public replies and internal notes) for a specific Zendesk ticket. Returns comment body, author, timestamps, and attachments.

Parameters:

- `ticket_id` (`number`, required): The ID of the ticket whose comments to list
- `include` (`string`, optional): Sideloads to include. Accepts 'users' to list email CCs.
- `include_inline_images` (`boolean`, optional): When true, inline images are listed as attachments (default: false)
- `sort_order` (`string`, optional): Sort direction for comments: asc or desc (default: asc)

### `zendesk_ticket_create`

Create a new support ticket in Zendesk. Requires a comment/description and optionally a subject, priority, assignee, and tags.

Parameters:

- `comment_body` (`string`, required): The description or first comment of the ticket
- `assignee_email` (`string`, optional): Email of the agent to assign the ticket to
- `priority` (`string`, optional): Ticket priority: urgent, high, normal, or low
- `status` (`string`, optional): Ticket status: new, open, pending, hold, solved, or closed
- `subject` (`string`, optional): The subject/title of the ticket
- `tags` (`array`, optional): List of tags to apply to the ticket
- `type` (`string`, optional): Ticket type: problem, incident, question, or task

### `zendesk_ticket_get`

Retrieve details of a specific Zendesk ticket by ID. Returns ticket properties including status, priority, subject, requester, assignee, and timestamps.

Parameters:

- `ticket_id` (`number`, required): The ID of the ticket to retrieve
- `include` (`string`, optional): Comma-separated list of sideloads to include (e.g., users, groups, organizations)

### `zendesk_ticket_reply`

Add a public reply or internal note to a Zendesk ticket. Set public to false for internal notes visible only to agents.

Parameters:

- `body` (`string`, required): The reply message content (plain text, markdown supported)
- `ticket_id` (`number`, required): The ID of the ticket to reply to
- `public` (`boolean`, optional): Whether the comment is public (true) or an internal note (false). Defaults to true.

### `zendesk_ticket_update`

Update an existing Zendesk ticket. Change status, priority, assignee, subject, tags, or any other writable ticket field.

Parameters:

- `ticket_id` (`number`, required): The ID of the ticket to update
- `assignee_email` (`string`, optional): Email of the agent to assign the ticket to
- `assignee_id` (`number`, optional): ID of the agent to assign the ticket to
- `group_id` (`number`, optional): ID of the group to assign the ticket to
- `priority` (`string`, optional): Ticket priority: urgent, high, normal, or low
- `status` (`string`, optional): Ticket status: new, open, pending, hold, solved, or closed
- `subject` (`string`, optional): New subject/title for the ticket
- `tags` (`array`, optional): List of tags to set on the ticket (replaces existing tags)
- `type` (`string`, optional): Ticket type: problem, incident, question, or task

### `zendesk_tickets_list`

List tickets in Zendesk with sorting and pagination. Returns tickets for the authenticated agent's account.

Parameters:

- `page` (`number`, optional): Page number for pagination
- `per_page` (`number`, optional): Number of tickets per page (max 100)
- `sort_by` (`string`, optional): Field to sort by: created_at, updated_at, priority, status, ticket_type
- `sort_order` (`string`, optional): Sort direction: asc or desc (default: desc)

### `zendesk_user_create`

Create a new user in Zendesk. Can create end-users (customers), agents, or admins. Email is required for end-users.

Parameters:

- `name` (`string`, required): Full name of the user
- `email` (`string`, optional): Primary email address of the user
- `organization_id` (`number`, optional): ID of the organization to associate the user with
- `phone` (`string`, optional): Primary phone number (E.164 format, e.g. +15551234567)
- `role` (`string`, optional): User role: end-user, agent, or admin. Defaults to end-user.
- `verified` (`boolean`, optional): Whether the user's identity is verified. Defaults to false.

### `zendesk_user_get`

Retrieve details of a specific Zendesk user by ID. Returns user profile including name, email, role, organization, and account status.

Parameters:

- `user_id` (`number`, required): The ID of the user to retrieve
- `include` (`string`, optional): Comma-separated list of sideloads to include

### `zendesk_users_list`

List users in Zendesk. Filter by role (end-user, agent, admin) with pagination support.

Parameters:

- `page` (`number`, optional): Page number for pagination
- `per_page` (`number`, optional): Number of users per page (max 100)
- `role` (`string`, optional): Filter by role: end-user, agent, or admin
- `sort` (`string`, optional): Field to sort by. Prefix with - for descending (e.g. -created_at)

### `zendesk_views_list`

List ticket views in Zendesk. Views are saved filters for organizing tickets by status, assignee, tags, and more.

Parameters:

- `access` (`string`, optional): Filter by access level: personal, shared, or account
- `page` (`number`, optional): Page number for pagination
- `per_page` (`number`, optional): Number of views per page (max 100)
- `sort_by` (`string`, optional): Field to sort by: title, updated_at, created_at, or position
- `sort_order` (`string`, optional): Sort direction: asc or desc


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |