> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Zendesk Integration: Tickets and Help Center for Agents

> Agents can read and search Zendesk tickets, reply to customers, add internal notes, and manage users and Help Center articles. Connect with your Zendesk OAuth client.

## Overview

OneCLI connects AI agents to [Zendesk](https://www.zendesk.com) with OAuth. Agents can read and search tickets, reply to customers or add internal notes, solve tickets, and manage users, organizations, and Help Center articles. The gateway adds the token to every request, so your agent never sees it.

This suits support agents: triaging new tickets, drafting a reply for a human to approve, or pulling a customer's history before an escalation.

Connecting takes about five minutes.

> [!NOTE]
>
> Zendesk is retiring API tokens. New tokens can't be created from October 27, 2026, and existing ones stop working on April 30, 2027. OneCLI uses OAuth, so nothing changes for you.

## Connect Zendesk

**1. Copy the Redirect URI from OneCLI**

In the OneCLI dashboard, open **Connections** > **Zendesk** and copy the **Redirect URI** shown in the connect window. Leave the window open.

**2. Create an OAuth client in Zendesk**

In Zendesk **Admin Center**, open **Apps and integrations** > **APIs** > **OAuth clients** and select **Add OAuth client**.

| Field | Value |
| - | - |
| **Name** | `OneCLI` |
| **Description** | `AI agents through OneCLI` |
| **Company** | Your company name |
| **Unique identifier** | `onecli` (or any unique name) |
| **Client kind** | **Confidential** |
| **Redirect URLs** | The Redirect URI you copied from OneCLI |

Select **Save**. Zendesk shows the **Secret** once, so copy it right away.

**3. Finish in OneCLI**

Back in the OneCLI connect window, fill in:

| Field | Value |
| - | - |
| **Subdomain** | The part before `.zendesk.com`, such as `acme` for `acme.zendesk.com` |
| **Client ID** | The OAuth client's **Unique identifier** |
| **Client Secret** | The secret from the previous step |

Select **Save & Connect**, sign in to Zendesk if asked, and select **Allow**. OneCLI names the connection after the Zendesk user who approved it.

![OneCLI connect screen reading 'OneCLI wants to connect to your Zendesk' with a link to the Zendesk setup guide and a Connect to Zendesk button.](https://mintcdn.com/chartdbinc/Oa7OKAPSog2HvGJH/images/integrations/zendesk/connect-zendesk.png?fit=max\&auto=format\&n=Oa7OKAPSog2HvGJH\&q=85\&s=02cdbbdc4c4b6058cb105dd98550852b)

OneCLI hands you off to Zendesk to sign in.

![Zendesk consent screen asking to allow the OneCLI OAuth client to access the Zendesk account, listing create, update, and delete data and view data, with Deny and Allow buttons.](https://mintcdn.com/chartdbinc/Oa7OKAPSog2HvGJH/images/integrations/zendesk/zendesk-allow-access.png?fit=max\&auto=format\&n=Oa7OKAPSog2HvGJH\&q=85\&s=5359982337cb1acb7669a6913abb6ff2)

Zendesk asks you to allow access. The name and description are the ones you gave the OAuth client.

> [!NOTE]
>
> Agents act as the Zendesk user who approved the connection, with that user's role and permissions. Connect with an agent or light agent account limited to what your AI agents should do, not a Zendesk admin.

## What agents can do

| Area | What agents can do |
| - | - |
| **Tickets** | List, read, and search tickets and their conversations, create tickets, and reply, add internal notes, change status, priority, assignee, or tags |
| **Bulk and cleanup** | Update many tickets at once, merge tickets, mark a ticket as spam, and delete tickets |
| **Users and organizations** | Read users and organizations, create and update users, and delete users |
| **Help Center** | Read articles and create new ones, as drafts or published |

Zendesk access tokens expire after 30 minutes. OneCLI renews them automatically, so a connection keeps working without anyone signing in again.

## Quick example

No `Authorization` header is needed. The gateway adds it:

```bash theme={null}
# Your newest open tickets
curl -s "https://acme.zendesk.com/api/v2/search.json?query=type:ticket%20status:open&sort_by=created_at&sort_order=desc"

# Add an internal note to ticket 123 (agents only, the customer doesn't see it)
curl -s -X PUT "https://acme.zendesk.com/api/v2/tickets/123.json" \
  -H "Content-Type: application/json" \
  -d '{"ticket": {"comment": {"body": "Checked the order: refund issued.", "public": false}}}'
```

For every endpoint and parameter, see the [Zendesk API reference](https://developer.zendesk.com/api-reference/).

## Controlling access

[Grant](https://onecli.sh/docs/guides/agent-access.md) the connection to each agent that needs it, and choose per tool what runs freely, what needs approval, and what's blocked.

A public reply reaches your customer right away. Approval cards say plainly whether a reply is **public** or an **internal note**, so you can let agents add notes freely and put public replies behind approval. **Delete tickets**, **Merge tickets**, **Mark ticket as spam**, and **Delete user** are tools of their own, so you can block them without blocking ordinary updates.

> [!WARNING]
>
> **Update tickets** also covers bulk updates (`/tickets/update_many`), which change many tickets in one request. Keep it behind approval unless you trust an agent with bulk changes.

Requests outside the tool list need approval by default, because some Zendesk endpoints return secrets, such as webhook signing secrets and the account's OAuth tokens.

Organization [rules](https://onecli.sh/docs/guides/rules.md) add guardrails on top. A blocked request never reaches Zendesk.

To disconnect, remove the connection in **Connections** > **Zendesk**, then delete the OAuth client in Zendesk under **Apps and integrations** > **APIs** > **OAuth clients**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.