Connect Zendesk#

Reportworq connects to Zendesk Support through a CData driver, which presents your Zendesk account as a relational, tabular source you query with the same table or SQL modes as any database. In the connector catalog the tile is Zendesk.

This page covers the Zendesk URL, creating the Zendesk OAuth client, registering the redirect URI, and signing in. For the shared CData add-and-test flow, see Connect CData sources.

Choose how Reportworq signs in#

Set the connection's Auth Scheme to the option that fits how you want Reportworq to reach Zendesk.

Auth Scheme	Use it when
OAuth (the default)	A Zendesk user signs in and authorizes Reportworq. Best for getting started. This page walks through it.
OAuthPKCE	Not recommended in Reportworq yet: the sign-in from the Reportworq web app does not support this variant. Use OAuth or APIToken instead.
APIToken	You sign in with a Zendesk email address and an API token. CData marks this option as deprecated, because Zendesk is retiring API token authentication (CData's documentation says by April 2027). Use OAuth for new connections. See Use an API token.

Before you begin#

You are an administrator in Reportworq. Only administrators can add or configure datasource connections.
Reportworq is reachable over HTTPS. OAuth sign-in cannot complete over plain http:// on a non-localhost address, and Reportworq stops with a message saying so.
You can sign in to Zendesk with an account that has admin access, to create the OAuth client.
You know your Zendesk Support URL, in the form https://<subdomain>.zendesk.com (see Find your Zendesk URL).

Find your Zendesk URL#

The connection's URL is your Zendesk Support address, in the format https://<subdomain>.zendesk.com, where <subdomain> is the first part of the address you use to open Zendesk Support in a browser. Enter the full address, including https://. The OAuth sign-in page is served from this same address, so a wrong subdomain also makes the sign-in fail.

Set up your Zendesk OAuth client#

Reportworq signs in through the server, not through a browser on the Reportworq machine, so it needs an OAuth client that you create in your own Zendesk account. CData's embedded OAuth application covers only desktop and headless sign-in, and CData states that web sign-in requires your own OAuth application.

The steps below follow CData's guide for the driver. Zendesk's admin menus change from time to time, so if a menu is named differently in your account, look for the page that manages OAuth Clients under the API settings.

Sign in to Zendesk with an account that has admin access.
In the Zendesk Support admin interface, go to Admin > Channels > API, and open the OAuth Clients tab.
Select the plus icon (+) to the right of the client list.
Complete the required fields. For the Redirect URI, add this exact address, replacing the host with your Reportworq address:
```
https://<your-reportworq-host>/server/v0/oauth-redirect
```
The redirect URI must match exactly, character for character, the address you reach Reportworq at. A mismatch is the most common cause of a failed sign-in.
Select Save. The page refreshes and shows a prepopulated Secret field.
Copy the client's unique identifier, which is the Client Id you give Reportworq, and the secret value, which is the Client secret. Treat the secret like a password.

Add the connection in Reportworq#

Sign in to Reportworq as an administrator and go to Settings > Integrations.
On the DATASOURCES tab, select Add, find Zendesk in the catalog, and add it. The connection editor opens.
In the General section at the top of the editor, select Enable Integration and give the connection a Display name. This is the name your formulas refer to, so it must be unique across the instance.
Enter your URL. Leave Auth Scheme at OAuth. Set Initiate OAuth to GETANDREFRESH so Reportworq can refresh the token for you, then enter your OAuth Client Id and OAuth Client Secret.
Save your changes. Selecting Authenticate with unsaved edits returns "Please save changes before performing this operation."
Select Authenticate. A new browser tab opens with the Zendesk sign-in on your Zendesk address. Sign in with a Zendesk account that can read the data you need and approve the request. When it completes, the tab tells you that authentication is complete. Close the tab and return to Reportworq.
Reportworq keeps the sign-in tokens encrypted in its own token store, separate from the connection, so the token fields in the OAuth section stay empty. That is expected. Select Test connection in the next step to confirm the sign-in worked.
Select Test connection, then Save.

To disconnect, select Sign out, which deletes this connection's stored tokens. Save any other edits first.

Use an API token#

Deprecated by Zendesk. CData's documentation says the API token scheme is being retired by Zendesk, and that tokens not used for 30 days are deactivated. Prefer OAuth.

In Zendesk, go to Admin > Channels > API, enable token access, and create an API token. Only one token can be active at a time, and deleting a token deactivates it permanently.
In Reportworq, set Auth Scheme to APIToken.
Enter your URL, set User to the email address of the Zendesk user, and set API Token to the active token.
Select Test connection, then Save. No Authenticate step is needed.

If User or API Token is empty, the driver reports that User / APIToken is required for APIToken authentication.

Query your Zendesk data#

Once the connection tests, a model author builds views over it on each view's Design tab, starting from a table or writing SQL, exactly as for the other CData and relational sources. See Build a view with the designer and Data models.

The connection exposes tables and views for the main Zendesk Support objects, among them Tickets, Users, Organizations, Groups, TicketComments, TicketAudits, TicketMetrics, TicketFields, TicketForms, SatisfactionRatings, Macros, Triggers, Automations, SlaPolicies, and Help Center content such as Articles, Sections, and Categories. CData's own reference lists every table and view and its columns: Zendesk ADO.NET provider docs.

Three optional settings under the connection's advanced options widen or tune what you can read:

Include Custom Objects (off by default) shows your Zendesk custom objects as tables. CData describes it as a costly operation, which is why it is off.
Include Custom Views (off by default) shows your Zendesk ticket views as read-only views, named after the Zendesk view title with spaces replaced by underscores.
Use Incremental API (default Auto) controls whether the driver uses the Zendesk Incremental API for large, date-filtered reads of tickets, users, organizations, and similar tables. CData notes that TicketMetrics queries over archived tickets need it set to True.

Behavior and limits#

Reportworq reads from Zendesk. Model authors build views over the connection and refresh them on job runs. This page covers reading your Zendesk data into data models.
Tokens are stored encrypted and refreshed automatically at run time. If the connection later stops authenticating, run Authenticate again.
Reportworq must be reached over HTTPS for the OAuth sign-in to complete.
Your Zendesk role matters. The connection signs in as one Zendesk user (or the API token's user), and CData notes that the Incremental API is only used under Auto when that user's role supports it.
Linux servers: when URL is your https://<subdomain>.zendesk.com address, every request the driver makes, including sign-in and token refresh, goes to that address, so on Linux Reportworq checks that site's certificate against the server's own trusted certificates before connecting. If Test connection still reports that server certificate verification failed, contact support and quote the message.
Only administrators can add or configure the connection, and editing, disabling, or deleting a live datasource breaks every job and form that refreshes from it.

Troubleshooting#

Symptom	Likely cause	What to do
Please save changes before performing this operation	You selected Authenticate or Sign out with unsaved edits	Save the connection, then try again.
Zendesk rejects the sign-in with a redirect error	The redirect URI in your Zendesk OAuth client does not match the address you reach Reportworq at	Set the client's Redirect URI to `https://<your-reportworq-host>/server/v0/oauth-redirect`, matching your address exactly.
Sign-in will not start, or fails to return	Reportworq is reached over plain `http://` on a non-localhost host	Reach Reportworq over HTTPS, then select Authenticate again.
The sign-in page cannot be found	The URL is empty, misspelled, or not your Zendesk subdomain	Enter the full address, `https://<subdomain>.zendesk.com`, and save before you authenticate.
User / APIToken is required for APIToken Authentication	Auth Scheme is APIToken but User or API Token is empty	Fill in both, or switch Auth Scheme back to OAuth.
A table returns fewer rows than you expect, or none	The signed-in Zendesk user cannot see that data	Sign in with a Zendesk account whose role can read it.
TicketMetrics does not cover archived tickets	CData says archived ticket metrics need the Incremental API forced on	Set Use Incremental API to True in the advanced options.
The connection works, then stops after the access token expires	No refresh token was stored, or Initiate OAuth is not GETANDREFRESH	Set Initiate OAuth to GETANDREFRESH, save, and select Authenticate again.

Connect CData sources for the shared CData add-and-test flow.
Connect QuickBooks Online, which uses the same server-side OAuth sign-in.
Connector catalog for every connector Reportworq ships.
Connect a data source for the general add, test, and manage flow.
Data models for turning the connection into curated, reusable data for report authors.

Feedback on this page

Comments, questions, requests, or something missing or unclear? Email us - the page you are on is filled in for you.

Email feedback on this page

Or write to support@reportworq.com directly.