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

# Zendesk setup

ConfigView reads your Zendesk account through the Zendesk API, signed in as a Zendesk **admin**, using an **API token** (or, optionally, an **OAuth client**) that you create in Zendesk Admin Center.

You will end up with **3 secrets** in ConfigView (`ZENDESK_SUBDOMAIN`, `ZENDESK_EMAIL`, `ZENDESK_API_TOKEN`) when setup is complete, or 2 more if you use the OAuth client.

> **Scope of this integration today.** ConfigView reads who your Zendesk admins and agents are and with what role, whether they use two-factor sign-in and when they last signed in, the apps installed in Zendesk, the OAuth apps and API tokens that can reach your Zendesk data, the webhooks that send ticket and user events to outside systems, and (on Enterprise plans) the audit log. It never reads tickets, ticket comments, or the customers who open tickets. ConfigView only reads. It never creates, changes or deletes anything.

***

## Step 1: Open the Zendesk page in ConfigView

Open ConfigView in a second browser tab and leave it open:

`https://{companyname}.configview.com/admin/integrations/zendesk`

Zendesk shows a new token once, when you create it, so paste it straight into ConfigView instead of keeping it in a notes file.

***

## Step 2: Enter your subdomain

Your subdomain is the part of your Zendesk address before `.zendesk.com`. For `https://acme.zendesk.com` it is `acme`.

Paste it into `ZENDESK_SUBDOMAIN` under **Credentials** and click the save icon.

***

## Step 3: Create an API token in Zendesk

1. Sign in to Zendesk as an **admin**. See *Which user the token acts as* below
2. Open **Admin Center → Apps and integrations → APIs → API tokens**
3. If token access is switched off, switch it on
4. Click **Add API token**, set the description to `ConfigView`, and click **Save**
5. Copy the token. Zendesk shows it only once
6. Switch to the ConfigView tab and paste it into `ZENDESK_API_TOKEN`. Put the email address of the admin you're signed in as into `ZENDESK_EMAIL`. Click the save icon after each

### Which user the token acts as

A Zendesk API token signs in as whichever user's email you pair it with, so `ZENDESK_EMAIL` decides what ConfigView can see.

* It must be an **admin**. Agents get a 403 on OAuth clients, OAuth tokens, API tokens, webhooks and the audit log, so those tables would stay empty. The health check stops here with a clear message if the user isn't an admin.
* If that admin leaves and their account is suspended or deleted, collection stops. A shared admin account that won't leave is the safer choice.

### Optional: sign in with an OAuth client instead

Zendesk is retiring API-token sign-in on **30 April 2027**. Before then, switch ConfigView to an OAuth client:

1. Signed in as an admin, open **Admin Center → Apps and integrations → APIs → OAuth clients → Add OAuth client**
2. Name it `ConfigView`, set the client kind to **Confidential**, and save
3. Copy the **Identifier** into `ZENDESK_OAUTH_CLIENT_ID` and the **Secret** (shown once) into `ZENDESK_OAUTH_CLIENT_SECRET`

When both are set, every collector uses the OAuth client and asks Zendesk only for the `read` scope. The email and API token are then ignored.

***

## Step 4: Connect and verify

1. Back on `https://{companyname}.configview.com/admin/integrations/zendesk`, confirm the credentials show as saved
2. Click **Connect**. ConfigView creates its tables and schedules every collector at your default run time. Stop any you don't want under **Collectors**:

| Script | Notes |
| - | - |
| **Admins and Agents** | Every Zendesk admin and agent (never the customers who open tickets): role, custom role, whether two-factor sign-in is on, suspended or deleted, and when they last signed in. |
| **Custom Agent Roles** | Custom agent roles (Enterprise plans): name, what kind of role it is, how many agents hold it, and the permissions it grants. |
| **Installed Apps** | Apps installed in Zendesk from the Marketplace or built privately: app name and author, whether it is enabled, paid, and limited to certain roles or groups. App settings are never read, because they can hold API keys. |
| **OAuth Clients** | OAuth clients registered on this Zendesk account (the integrations allowed to ask users for API access): name, company, which admin created it, allowed scopes and the hosts it redirects to. The client secret is never read. |
| **Authorized Marketplace OAuth Apps** | Third-party OAuth apps that people on this account have authorized, with how many live tokens they hold and when one was last used. |
| **OAuth Tokens** | Every OAuth access token on the account: which client and which user it belongs to, its scopes, when it was created, last used and when it expires. Token values are never read. |
| **Webhooks** | Webhooks that send Zendesk ticket and user events to outside systems: the destination host, which events, active or not, how they authenticate (type only), and who created them. |
| **API Tokens** | API tokens on the account: description, active or not, who created it, and when it was created and last used. Token values are never read. |
| **Audit Log** | Zendesk's audit log (Enterprise plans): who signed in, exported data, or changed users, roles, settings, apps and rules, from which IP address, and what changed. Kept as a growing history. |

3. Click **Verify now**. The health check confirms the credentials, signs in, checks the user is an admin, then reads one record from each list.

If a check fails:

* **Auth fails with 401.** The email and token don't match, the token was deleted, or token access was switched off in Admin Center. `ZENDESK_EMAIL` is the plain email address, without `/token`.
* **"Credential is a Zendesk admin" fails.** The email belongs to an agent. Use an admin's email (and a token that admin can use).
* **Custom agent roles or Audit log are skipped with 403/404.** Expected below the Enterprise plan. Zendesk only offers these on Enterprise.
* **API tokens is skipped with 404.** API-token access is switched off for the account. Expected if you sign in with the OAuth client.

***

## Data Tables

Once the scripts run, these tables are created in your database. Each includes a `run_at` column for historical tracking, and a `raw_json` column holding the record as Zendesk returned it, minus the fields listed under *What isn't collected*. Every table keeps only the newest run, except `zendesk_audit_logs`, which keeps every event it has ever read.

| Table | Source | Key Columns |
| - | - | - |
| `zendesk_users` | `GET /api/v2/users?role[]=admin&role[]=agent` | user\_id, email, name, role, role\_type, role\_label, custom\_role\_id, active, suspended, two\_factor\_auth\_enabled, restricted\_agent, last\_login\_at, created\_at, updated\_at |
| `zendesk_custom_roles` | `GET /api/v2/custom_roles` | role\_id, name, description, role\_type, role\_label, team\_member\_count, configuration, created\_at, updated\_at |
| `zendesk_app_installations` | `GET /api/v2/apps/installations?include=app` | installation\_id, app\_id, app\_name, installation\_title, enabled, product, paid, pending\_installation, role\_restrictions, group\_restrictions, app\_author\_name, app\_visibility, app\_short\_description, created\_at, updated\_at |
| `zendesk_oauth_clients` | `GET /api/v2/oauth/clients` | client\_id, name, identifier, company, description, kind, user\_id, redirect\_hosts, allowed\_scope, is\_global, created\_at, updated\_at |
| `zendesk_oauth_global_clients` | `GET /api/v2/oauth/global_clients` + `/token_summary` | global\_client\_id, name, identifier, company, description, kind, tokens\_count, last\_used\_at |
| `zendesk_oauth_tokens` | `GET /api/v2/oauth/tokens?all=true` | token\_id, client\_id, user\_id, scopes, created\_at, used\_at, expires\_at, refresh\_token\_expires\_at |
| `zendesk_webhooks` | `GET /api/v2/webhooks` | webhook\_id, name, description, endpoint\_host, http\_method, status, subscriptions, request\_format, auth\_type, auth\_add\_position, has\_custom\_headers, external\_source\_type, external\_app\_id, external\_installation\_id, created\_by, updated\_by, created\_at, updated\_at |
| `zendesk_api_tokens` | `GET /api/v2/api_tokens?include_users=true` | token\_id, description, active, user\_id, user\_name, user\_email, assigned\_user\_id, created\_at, updated\_at, last\_used\_at |
| `zendesk_audit_logs` | `GET /api/v2/audit_logs` | audit\_log\_id, actor\_id, actor\_name, action, action\_label, source\_type, source\_id, source\_label, ip\_address, change\_description, created\_at |

***

## Things worth knowing

**Customers are never collected.** In Zendesk, everyone who has ever opened a ticket is a user with the role "end-user". ConfigView asks only for admins and agents, so `zendesk_users` is your staff.

**`role_label` spells out the role.** Zendesk stores agent types as numbers (`role_type`). `role_label` reads `admin`, `light agent`, `custom agent`, `contributor` and so on. On Enterprise, `custom_role_id` joins to `zendesk_custom_roles.role_id`.

**The audit log is a growing history.** The first run reads every event Zendesk still holds, oldest first. After that each run picks up from the newest stored event, so nothing is read twice and nothing is ever deleted.

**People are named by Zendesk user id.** OAuth tokens, OAuth clients and audit events carry a Zendesk `user_id` / `actor_id`. Join to `zendesk_users.user_id` for the name and email.

**Webhooks and redirect URIs show the host only.** Full URLs can carry tokens in their path or query string, so ConfigView keeps `hooks.example.com`, not the address.

**API tokens are on their way out.** Zendesk retires API tokens on 30 April 2027. After that `zendesk_api_tokens` stops filling, and you'll need the OAuth client to keep collecting.

**Rate limits are shared.** Zendesk allows each account a number of API requests per minute by plan (200 on Team, 400 on Growth and Professional, 700 on Enterprise). Every integration shares it. ConfigView paces itself at 60 a minute and pauses when Zendesk reports the account is nearly out.

## What isn't collected

* Tickets, ticket comments, attachments, and the customers (end-users) who open tickets
* App installation settings, which can hold an app's API keys or passwords
* OAuth client secrets, OAuth access and refresh tokens, and API token values (not even the first characters)
* Webhook credentials, custom headers and signing secrets. Only the type of authentication (`basic_auth`, `bearer_token`, `api_key`) is kept
* Agent notes, signatures, phone numbers and custom user fields


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