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

Sign in to Zendesk as an admin. See Which user the token acts as below
Open Admin Center → Apps and integrations → APIs → API tokens
If token access is switched off, switch it on
Click Add API token, set the description to ConfigView, and click Save
Copy the token. Zendesk shows it only once
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.

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

Signed in as an admin, open Admin Center → Apps and integrations → APIs → OAuth clients → Add OAuth client
Name it ConfigView, set the client kind to Confidential, and save
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

Back on https://{companyname}.configview.com/admin/integrations/zendesk, confirm the credentials show as saved
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.

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

Platform

Integrations

Step 1: Open the Zendesk page in ConfigView

Step 2: Enter your subdomain

Step 3: Create an API token in Zendesk

Which user the token acts as

Step 4: Connect and verify

Data Tables

Things worth knowing

What isn’t collected

​Step 1: Open the Zendesk page in ConfigView

​Step 2: Enter your subdomain

​Step 3: Create an API token in Zendesk

​Which user the token acts as

​Optional: sign in with an OAuth client instead

​Step 4: Connect and verify

​Data Tables

​Things worth knowing

​What isn’t collected

Step 1: Open the Zendesk page in ConfigView

Step 2: Enter your subdomain

Step 3: Create an API token in Zendesk

Which user the token acts as

Optional: sign in with an OAuth client instead

Step 4: Connect and verify

Data Tables

Things worth knowing

What isn’t collected