Zendesk

Authentication & Authorization

Credentials

• DataGrail support two different connection methods for Zendesk:
  • OAuth 2.0 with Authorization Code Grant Flow (recommended):
    • DataGrail owns a Zendesk OAuth 2.0 App that provides the credentials to authenticate customers allowing the integration to connect by simply logging into their Zendesk account with their admin credentials and accepting to install the app.
    • OAuth grants granular permissions to the API so DataGrail only accesses required resources to provide our services.
  • API Token:
    • Connects via basic authentication using a special API Key as credentials.
    • API Key is set with the HTTP Authorization request header.
    • Your API Key can be created in the Zendesk Admin Center in the Apps and integrations menu.
• Publicly exposing your API credentials can allow unauthorized access to the Zendesk API endpoints, and your Zendesk data by a third party. DataGrail stores your API keys encrypted and protected.
• See also Zendesk Connection Instructions.

Scopes

For Zendesk OAuth connection DataGrail requires customers grant specific and limited scopes in order to provide its services for access and deletion privacy requests, as well as periodic system detection:

• read (global "read")
• users:write
• tickets:write

Scopes are independent of the required integration capabilities and the same for Access, Deletion, System Detection and Responsible Data Discovery

Base URL

Base URL consists of the Subdomain, API URL and API version:

• https://{SUBDOMAIN}.zendesk.com/api/v2

Example of BASE URL:

• https:​//mycompany.zendesk.com/api/v2

Subdomain can be identified from the account's URL (see Zendesk Connection Instructions)

Endpoints Utilized

OAuth 2.0:

• Request authorization:
  • GET https://{SUBDOMAIN}.zendesk.com/oauth/authorizations/new
• Get and refresh access token:
  • POST https://{SUBDOMAIN}.zendesk.com/oauth/tokens
• DataGrail uses the following endpoint to validate that connection is good based on a successful response:
  • GET {BASE_URL}/users

API Token:

• DataGrail uses the following endpoint to validate that connection is good based on a successful response:
  • GET {BASE_URL}/users

Version

DataGrail Zendesk integration currently supports API version 2 (v2).

Limits

DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

Access

When looking for data subjects PII in Zendesk, DataGrail focuses the search around Users, who can be End Users (i.e. people external to your company) or can be Agents (i.e.employees of your company).

When looking for both Users, DataGrail will try to find that person using email as the primary identifier. If found, DataGrail will then proceed to find all the associated objects that may potentially contain PII. These objects are:

• Search Users: Search End Users and Agents.
• Identities: A user identity is something that can be used to identify an individual. Most likely, it's an email address, a Twitter handle, or a phone number.
• Tickets: Tickets are the means through which your end users communicate with agents in Zendesk. A ticket is an agent's perspective on a ticket.
• Requests: A request is an end user's perspective on a ticket.
• Organizations: End user segmentation.

If Ticket audits metadata is enabled (see Zendesk Connection Instructions), DataGrail will take additional following actions:

• Fetch audit history of all updates to each of detected tickets.
• Save audit metadata, such as IP, client, location as an additional data object.

When reviewing data returned by Zendesk please note the following:

• Only fields with values are returned.
• Custom fields unique to the organization may also be returned if they may potentially contain PII.
• You can edit which objects and fields you want to provide to the Data Subject via our Portal Requests.

Endpoints Utilized

• GET {BASE_URL}/users/search
• GET {BASE_URL}/users/user_id/identities
• GET {BASE_URL}/users/user_id/organizations
• GET {BASE_URL}/users/user_id/requests
• GET {BASE_URL}/users/user_id/tickets/requested
• GET {BASE_URL}/tickets/{ticket_id}/audits

note

DataGrail also supports the Direct Contact Access workflow for Zendesk.

Deletion

DataGrail supports deletion of Users (both End Users and Agents) as well as Tickets.

For a deletion request, DataGrail will take the following actions:

Step 1. Search for personal data

• Search End Users and Agents by the Data Subject email.
• If user found, search tickets requested by the user.
• If tickets found, request bulk tickets deletion.
• Save bulk tickets deletion job ID.
• Create a scheduling task for regular checking of the bulk tickets deletion by job ID.

Step 2. Delete personal data

When tickets deleted:

• Deletes the user and associated records from the account
• Permanently Delete User

Endpoints Utilized

• GET {BASE_URL}/users/search
• GET {BASE_URL}/users/user_id/tickets/requested
• DELETE {BASE_URL}/tickets/destroy_many
• GET {BASE_URL}/job_statuses/{job_status_id}
• DELETE {BASE_URL}/users/id
• DELETE {BASE_URL}/deleted_users/id

note

DataGrail also supports the Direct Contact Deletion workflow for Zendesk.

System Detection

DataGrail provides continuous system detection, delivering a real-time inventory of your data assets.

For an system detection requests, DataGrail will take the following actions:

• Read app installations in the account
• Read user fields
• Read organizations fields

Endpoints Utilized

• GET {BASE_URL}/apps/installations
• GET {BASE_URL}/user_fields
• GET {BASE_URL}/organization_fields

Responsible Data Discovery

Data discovery is based on the principle of finding any and all personal data that's stored in a data system (see more).

Currently, DataGrail integration discovery processes the following Zendesk objects:

• tickets
• users

For discovery requests, DataGrail will take the following actions:

• Count number of all records for each of supported objects.
• Fetch records examples for each of the supported object.
• Sampling data for the next analysis and classification.

Endpoints Utilized

• GET {BASE_URL}/tickets/count
• GET {BASE_URL}/tickets
• GET {BASE_URL}/users/count
• GET {BASE_URL}/users