Zendesk

Zendesk integration allows your product to create, read, and manage tickets within Zendesk's customer support and incident management system. This integration is ideal for vulnerability tracking, incident reporting, and security operations, where detected issues or alerts in your product can be automatically converted into Zendesk tickets for triage and resolution. It supports both Zendesk Support and Zendesk Service Management instances via the Zendesk REST API v2.

Credentials Needed

To connect to Zendesk's REST API, you need an API-enabled account with appropriate access rights.

Required credentials:

• Zendesk Subdomain / Instance URL (e.g., https://companyname.zendesk.com)
• Email Address (of the Zendesk user or integration account)
• API Token (generated from Zendesk Admin Center)

Zendesk uses Basic Authentication via the pattern:

Authorization: Basic base64("user@example.com/token:API_TOKEN")

Permissions Needed / API Scopes

Zendesk roles determine the level of access your integration has.

Role	Description
Agent	Can view and manage tickets assigned to groups
Admin	Can create/update any ticket, view all tickets, manage users
Custom Role (recommended)	Create a dedicated API user with minimal ticket permissions

Minimum Required Role: Agent with ticket read/write permissions

For enterprise or multi-tenant products, it's recommended to create a dedicated "Integration User" with an API token and least-privilege access.

Creating Users / Access Tokens

Step 1: Enable API Access

1. Log in to your Zendesk Admin Center: https://companyname.zendesk.com/admin
2. Navigate to Apps and Integrations → APIs → Zendesk API
3. Ensure Token Access is enabled

Step 2: Create an API Token

1. Under Active API Tokens, click + Add API Token
2. Provide a name/label (e.g., IntegrationToken)
3. Copy the generated token — it will only be shown once
4. Click Save
5. Store the following values securely:
   • Email: user@example.com
   • API Token: abcd1234xyz
   • Instance URL: https://companyname.zendesk.com

Test Connectivity

You can test your credentials using curl:

Example: List All Tickets

curl -u "user@example.com/token:<API_TOKEN>" \
  -H "Content-Type: application/json" \
  "https://companyname.zendesk.com/api/v2/tickets.json"

Example Response:

{
  "tickets": [
    {
      "id": 101,
      "subject": "Critical SQL Injection vulnerability",
      "status": "open",
      "priority": "high",
      "created_at": "2025-10-13T11:20:00Z",
      "assignee_id": 202345
    }
  ]
}

Example: Get Current User Info

curl -u "user@example.com/token:<API_TOKEN>" \
  "https://companyname.zendesk.com/api/v2/users/me.json"

Example Response:

{
  "user": {
    "id": 123456,
    "name": "Security Bot",
    "role": "admin",
    "email": "user@example.com"
  }
}

Create a New Ticket

Request:

curl -X POST \
  -u "user@example.com/token:<API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": {
      "subject": "RCE vulnerability in production API",
      "comment": {
        "body": "A critical Remote Code Execution vulnerability was detected in the /upload endpoint."
      },
      "priority": "urgent",
      "type": "incident",
      "tags": ["security", "critical"],
      "requester": {"email": "security-alerts@company.com"}
    }
  }' \
  "https://companyname.zendesk.com/api/v2/tickets.json"

Example Response:

{
  "ticket": {
    "id": 104,
    "subject": "RCE vulnerability in production API",
    "status": "new",
    "priority": "urgent",
    "url": "https://companyname.zendesk.com/api/v2/tickets/104.json"
  }
}

Save the Results in the Platform and Create Connection

1. In your product's integration module, securely store:
   • ZENDESK_INSTANCE_URL
   • ZENDESK_EMAIL
   • ZENDESK_API_TOKEN
2. Label the connection as Zendesk Integration
3. Test connectivity by listing tickets or users
4. On success, enable workflows such as:
   • Auto-create Zendesk tickets for new vulnerabilities or incidents
   • Sync ticket statuses and comments to your product
   • Add internal notes from your platform directly to Zendesk

Best Practices

• Use a dedicated API user account (not a personal account)
• Store all credentials securely in your secret vault
• Rotate API tokens regularly (every 90 days)
• Apply least privilege permissions — restrict to specific groups or ticket types
• Respect Zendesk's rate limits (typically 700 requests/minute per account)
• Use pagination (page[size] and page[after] parameters) for large ticket lists
• Tag tickets with your platform name (e.g., created_by=SecurityPlatform)
• Use the ticket id or external_id field to link your internal entity (e.g., vulnerability ID) to Zendesk
• Handle rate limit responses (HTTP 429) using exponential backoff

Useful Zendesk API Endpoints

Resource	Method	Endpoint	Description
List tickets	GET	/api/v2/tickets.json	Lists all tickets
Get ticket details	GET	/api/v2/tickets/{id}.json	Fetch single ticket details
Create ticket	POST	/api/v2/tickets.json	Create a new ticket
Update ticket	PUT	/api/v2/tickets/{id}.json	Update ticket status, priority, etc.
Add comment	POST	/api/v2/tickets/{id}.json	Add comment to a ticket
List users	GET	/api/v2/users.json	List Zendesk users
Get user info	GET	/api/v2/users/me.json	Get authenticated user info
List ticket audits	GET	/api/v2/tickets/{id}/audits.json	Retrieve change history

Official Documentation: https://developer.zendesk.com/api-reference/ticketing/introduction/

Webhook Integration (Optional)

To sync ticket updates from Zendesk to your product:

1. In Admin Center → Apps and Integrations → Webhooks → Create Webhook
2. Set Endpoint URL = your platform's webhook listener
3. Choose Event Trigger: Ticket Created / Updated / Solved / Closed
4. Format: application/json
5. Test and save

Zendesk will now POST real-time ticket updates to your platform for synchronization.

Example JSON Payload for Ticket Creation

{
  "ticket": {
    "subject": "SQL Injection vulnerability detected in /auth endpoint",
    "comment": {
      "body": "Scanner detected a critical SQLi vulnerability. Immediate remediation required."
    },
    "priority": "high",
    "type": "incident",
    "tags": ["security", "vulnerability"],
    "requester": {"email": "security@company.com"}
  }
}

Example JSON Response

{
  "ticket": {
    "id": 556,
    "subject": "SQL Injection vulnerability detected in /auth endpoint",
    "status": "new",
    "priority": "high",
    "created_at": "2025-10-13T11:50:00Z",
    "url": "https://companyname.zendesk.com/api/v2/tickets/556.json"
  }
}