# Zendesk

Connecting Zendesk gives SureCloud read access to your Zendesk account's tickets, users, groups, roles, and audit log events. SureCloud uses Zendesk as a source of operational evidence — collecting tickets tagged or categorised as compliance or security-related, verifying SLA policy configuration and breach rates, auditing agent and administrator access to confirm that permissions are appropriate, and reading the Zendesk audit log for administrative activity. This provides evidence that your support and ticketing environment is governed and that compliance-relevant ticket workflows are progressing appropriately.

{% hint style="info" %}
SureCloud connects to Zendesk using OAuth 2.0 where supported, or an API token with a dedicated service account for instances where OAuth is preferred for simplicity. Both methods are fully supported.
{% endhint %}

## Authentication and setup

{% tabs %}
{% tab title="OAuth 2.0 (recommended)" %}
{% stepper %}
{% step %}

#### Create an OAuth client in Zendesk

In your Zendesk Admin Centre, navigate to **Apps and integrations → APIs → Zendesk API → OAuth Clients → Add OAuth client**.

* **Client name**: `SureCloud CCM`
* **Description**: SureCloud Continuous Control Monitoring
* **Company**: your organisation name
* **Logo**: optional
* **Redirect URLs**: enter the SureCloud OAuth callback URL provided in **SureCloud → Integrations → Zendesk → Connect**

Click **Save** and note the **Client ID** and generated **Secret**.
{% endstep %}

{% step %}

#### Initiate the OAuth flow in SureCloud

In SureCloud, navigate to **Integrations → Zendesk → Connect** and provide:

* **Zendesk subdomain** (e.g. `yourcompany` from `yourcompany.zendesk.com`)
* **Client ID**
* **Client Secret**

Click **Connect via OAuth**. SureCloud redirects to your Zendesk login. Authenticate as an Administrator account and approve the authorisation request.

SureCloud requests the following scopes:

| Scope             | Purpose                                                     |
| ----------------- | ----------------------------------------------------------- |
| `read`            | Read tickets, users, groups, and organisation data          |
| `tickets:read`    | Read ticket content and metadata                            |
| `users:read`      | Read agent and end-user profiles                            |
| `audit_logs:read` | Read Zendesk audit log events (Administrator accounts only) |
| {% endstep %}     |                                                             |
| {% endstepper %}  |                                                             |
| {% endtab %}      |                                                             |

{% tab title="API Token" %}
{% stepper %}
{% step %}

#### Enable API token access

In Zendesk Admin Centre, navigate to **Apps and integrations → APIs → Zendesk API** and ensure **Token access** is enabled.
{% endstep %}

{% step %}

#### Create a dedicated service account

In **People → Team → Add team member**, create a service account (e.g. `surecloud-ccm@yourcompany.com`) and assign it the **Administrator** role. The Administrator role is required to read the audit log and full agent permission data.
{% endstep %}

{% step %}

#### Generate an API token

In **Apps and integrations → APIs → Zendesk API → API token → Add API token**, create a token named `SureCloud CCM`. Copy the token value immediately.

In SureCloud, navigate to **Integrations → Zendesk → Connect (API Token)** and provide:

* **Zendesk subdomain**
* **Email address** of the service account (`surecloud-ccm@yourcompany.com`)
* **API token**

SureCloud authenticates using the `{email}/token:{api_token}` Basic Auth format that Zendesk requires for token-based access.

{% hint style="warning" %}
Rotate this token every 90 days and update it in **SureCloud → Integrations → Zendesk → Edit Connection**. If the service account email address changes, both the email and token fields must be updated.
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

## Endpoints

| API Call                        | Use Case                                                                                                        |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `GET /api/v2/tickets`           | Enumerate tickets within the collection window; filter by tags or custom fields for compliance-relevant tickets |
| `GET /api/v2/tickets/{id}`      | Read full ticket record including status, assignee, SLA breach state, and custom field values                   |
| `GET /api/v2/users`             | Enumerate all agents and administrators with their role and active status                                       |
| `GET /api/v2/groups`            | List agent groups and their membership                                                                          |
| `GET /api/v2/slas/policies`     | Read SLA policy definitions and their target response and resolution times                                      |
| `GET /api/v2/tickets/{id}/slas` | Read SLA status per ticket; detect breached and at-risk tickets                                                 |
| `GET /api/v2/audit_logs`        | Read Zendesk administrator audit log events                                                                     |
| `GET /api/v2/roles`             | Enumerate custom agent roles and their permission sets                                                          |
| `GET /api/v2/organizations`     | List organisations (used for ticket scoping and access governance)                                              |

## Pagination

The Zendesk API uses cursor-based pagination via a `next_page` URL in the response body for most list endpoints. SureCloud follows the `next_page` URL until it is `null`.

```json
{
  "tickets": [
    { "id": 10042, "subject": "Security patch review", "status": "open", "tags": ["compliance", "sla-breach"] }
  ],
  "next_page": "https://yourcompany.zendesk.com/api/v2/tickets?page[after]=eyJvIjoibmlkIiwiYSI6dHJ1ZX0%3D",
  "previous_page": null,
  "count": 8341
}
```

For the audit log endpoint, Zendesk uses an `after_cursor` parameter. SureCloud passes the cursor from each response's `before_cursor` field (Zendesk audit logs are returned in reverse chronological order) until the collection window is covered.

## Required permissions

The authorising account (OAuth) or service account (API token) must hold the **Administrator** role in Zendesk to access the audit log and full user permission data. Agent-level accounts can read tickets and users but cannot access `audit_logs` or `roles` endpoints.

{% hint style="info" %}
Zendesk audit logs are available on **Suite Professional** plans and above, and on legacy **Enterprise** plans. On lower-tier plans, the `/api/v2/audit_logs` endpoint returns a 403 error. SureCloud skips audit log collection for accounts where this endpoint is unavailable and collects all other data normally.
{% endhint %}

## Polling frequency

| Data type                | Collection interval |
| ------------------------ | ------------------- |
| Tickets and SLA status   | 4 hours             |
| User and group inventory | 24 hours            |
| SLA policy configuration | 24 hours            |
| Audit log events         | 6 hours             |
| Custom role definitions  | 24 hours            |

## Troubleshooting

<details>

<summary>Audit log events are not appearing</summary>

The Zendesk audit log requires an **Administrator** account and a **Suite Professional** or **Enterprise** plan. On lower-tier plans the endpoint returns 403, and SureCloud will skip audit log collection without failing the overall connection.

Confirm your Zendesk plan in **Admin Centre → Account → Billing → Plan** and that the authenticating account holds the Administrator role.

</details>

<details>

<summary>Compliance-tagged tickets are not appearing in SureCloud</summary>

SureCloud filters tickets using tag or custom field criteria configured during integration setup. If the tags or field values used in your Zendesk instance do not match the default filter configuration, tickets will not be collected.

Navigate to **SureCloud → Integrations → Zendesk → Configure** to review and update the ticket filter criteria to match the tags or custom fields your team uses to identify compliance-relevant tickets.

</details>

<details>

<summary>SLA breach data is missing for some tickets</summary>

SLA policies are only available on Zendesk **Suite Growth** plans and above. On the Support-only or Suite Team plan, SLA policies do not exist and the `/slas/policies` endpoint returns an empty list. SureCloud reports SLA data where it is available and omits it for accounts without SLA policy support.

If your plan supports SLAs but breach data is missing for specific tickets, confirm the ticket has an SLA policy applied in **Ticket → SLA** within the Zendesk agent interface.

</details>

<details>

<summary>OAuth token is returning scope errors after reconnection</summary>

Zendesk OAuth tokens are tied to the scopes granted at the time of authorisation. If the required scopes were not all approved during the OAuth flow, some endpoints will return 403 errors even though the connection succeeds.

Re-connect via **SureCloud → Integrations → Zendesk → Reconnect** and ensure all requested scopes are approved during the OAuth authorisation step.

</details>

<a href="https://developer.zendesk.com/api-reference/" class="button secondary">Zendesk API reference</a> <a href="https://developer.zendesk.com/documentation/ticketing/working-with-oauth/creating-and-using-oauth-tokens-with-the-api/" class="button secondary">Zendesk OAuth documentation</a>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/zendesk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.