# Zendesk Ticketing Provider Configuration Guide

This guide provides step-by-step instructions for configuring the Zendesk ticketing integration with our platform. By following these instructions, you'll be able to successfully set up and connect your Zendesk Support instance to enable ticket management and synchronization aligned with how the integration authenticates and calls the Zendesk API today.

## Overview

Zendesk uses **HTTP Basic authentication** with an API token. See Zendesk’s [Security and authentication](https://developer.zendesk.com/api-reference/introduction/security-and-auth/#api-token) for more detail.

## Authentication Steps

### 1. Obtain or create an API token

1. Ensure you can open **Zendesk Admin Center** for your instance (admins typically use the **Admin Center** launcher from the Support product toolbar; Zendesk publishes navigation help in **[How can I authenticate API requests?](https://support.zendesk.com/hc/en-us/articles/4408831452954-How-can-I-authenticate-API-requests)** and related docs).
2. Go to **Apps and integrations → APIs → Zendesk API**. On that page use **API tokens** (or **Token Access** depending on Zendesk’s current UI labeling) to **Add API token** (or equivalent).
3. Optionally add a descriptive label so you can rotate tokens safely later (Zendesk allows multiple active tokens, up to their documented limits—see **[Managing API token access to the Zendesk API](https://support.zendesk.com/hc/en-us/articles/4408889192858-Managing-API-token-access-to-the-Zendesk-API)**).


Official reference: **[Zendesk API token authentication](https://developer.zendesk.com/api-reference/introduction/security-and-auth/#api-token)**.

> **Note:** Treat the token as a secret shared only with integrations that need it. Rotate it at once if leaked, and update the credential everywhere it is configured (including Synqly).


### 2. Determine your Zendesk base URL

The integration expects a **single HTTPS base URL** for your Zendesk tenant, typically:


```
https://YOUR_SUBDOMAIN.zendesk.com
```

Replace `YOUR_SUBDOMAIN` with the subdomain assigned to your Support instance—that is usually the host you already use when agents sign in.

The URL validation and connection testing logic derive the subdomain from an `*.zendesk.com` hostname. Use only the tenant **origin** (scheme + host)—no trailing path segments such as `/api/v2/...`.

## Configure the Integration

Create your integration by supplying the following values:

| Parameter | Description |
|  --- | --- |
| **URL** | HTTPS base URL for your Zendesk tenant (for example `https://YOUR_SUBDOMAIN.zendesk.com`) |
| **Username** | Exactly **`YOUR_EMAIL/token`** — your Zendesk user’s email, followed by the literal string `/token`. (Example: **`agent@yourcompany.com/token`**) |
| **Secret** | The **API token** string from Admin Center—not your interactive login password |


The runtime sends these as HTTP Basic auth **without** rewriting the username field. Ensure you include **`/token`** after the email if your integration exposes separate username/password fields.

If your platform references stored credentials by ID, configure the credential that maps to Basic auth with **`username`** = `email/token` and **secret** = token.

## Troubleshooting

If something fails:

- **401 / auth failures:** Confirm the username is literally **`you@yourcompany.com/token`** (not email alone) and the secret is the active **Admin Center API token**.
- **URL errors:** The URL must be **HTTPS** and match your host (normally `https://SUBDOMAIN.zendesk.com` without extra path segments).
- **Subdomain issues:** Recover the subdomain from your Support login URL or admin settings and rebuild the base URL accordingly.
- **Permissions:** Use an agent email whose role can manage the tickets your integration touches. If actions fail with forbidden errors, widen that user’s Zendesk permissions or use a dedicated integration user profile.


## Additional Resources

- [Zendesk REST API introduction](https://developer.zendesk.com/api-reference/)
- [Zendesk API token authentication (`email/token`)](https://developer.zendesk.com/api-reference/introduction/security-and-auth/#api-token)