Zendesk Port

Purpose

This is the Harbor reference integration for the Zendesk Ticketing API.

Use it when:

• building Zendesk actions in Harbor
• extending the Dock / Hub Zendesk entry
• teaching Codex or OpenClaw how to map support ticket reads and bounded ticket creation into Harbor Ports and Harbor Actions without turning Harbor into a generic helpdesk admin proxy

Harbor Port worksheet

Product

• Product: Zendesk Ticketing API
• Publisher slug: zendesk
• Publisher name: Zendesk
• Category: CRM
• Tags: zendesk, support, tickets, customer-ops, helpdesk

Safe Harbor Port metadata

• Kind: http_api
• Label: Zendesk API
• Description: Zendesk API connection managed locally through Harbor.
• Base URL: tenant-specific Zendesk subdomain root, for example https://acme.zendesk.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

For Harbor Dock distribution, prefer OAuth bearer tokens over Zendesk basic auth with API tokens.

Harbor action design notes

Zendesk is a good Harbor fit when we keep tenant targeting explicit, ticket reads bounded, and ticket creation reviewable.

Good Harbor Zendesk starter actions:

• fixed GET reads for ticket inventory with typed pagination and sorting filters
• a bounded GET route for one explicit ticket ID
• one reviewable POST route for ticket creation
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for create-ticket
• resultMode: "json_summary" for all starter actions

Avoid for now:

• bulk update, merge, delete, or spam workflows
• generic search passthroughs across the full ticketing surface
• admin configuration, user management, or macro/rule mutation flows
• agent-impersonation or credential-sharing patterns

Starter Zendesk actions

Automatic read actions

• list-tickets -> GET /api/v2/tickets
• get-ticket -> GET /api/v2/tickets/{ticketId}

Approval-friendly write actions

• create-ticket -> POST /api/v2/tickets

Why these actions

These routes fit Harbor's current safe model because they:

• stay on stable REST endpoints under one explicit tenant base URL
• keep ticket targeting explicit through bounded path templates
• use typed query parameters for reviewable list behavior instead of generic query forwarding
• expose ticket creation as a named capability instead of generic authenticated HTTP access

Action Model notes

At execution time, callers supply values by location:

• input.query for list-tickets
• input.path.ticketId and optional input.query.include for get-ticket
• input.body for create-ticket

Example ticket listing request:

{
  "query": {
    "per_page": 25,
    "sort_by": "updated_at",
    "sort_order": "desc"
  }
}

Example single-ticket request:

{
  "path": {
    "ticketId": 12345
  }
}

Example create request:

{
  "body": {
    "ticket": {
      "subject": "Customer cannot access billing portal",
      "comment": {
        "body": "Customer reports repeated login failures after password reset."
      },
      "priority": "high"
    }
  }
}

For create-ticket, keep the body bounded to fields you actually intend to support, such as:

• subject
• comment
• priority
• requester
• requester_id
• type
• tags

Safety note for ticket creation

create-ticket stays on require_approval because ticket creation can trigger agent workflows, outbound notifications, routing rules, and customer-facing support activity. Harbor should treat that as an explicit, reviewable capability.

Suggested operator workflow

1. Import the Zendesk Dock entry from Dock / Hub.
2. Configure the local Zendesk tenant base URL in Harbor Node.
3. Configure the local OAuth bearer token in Harbor Node.
4. Use list-tickets to inspect current ticket volume and filters.
5. Use get-ticket to inspect the exact record shape you need.
6. Keep create-ticket on require_approval unless there is a very clear local policy reason not to.

Suggested agent workflow

1. Inspect the existing Zendesk Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed Zendesk routes only when they remain bounded and reviewable.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored Zendesk token
• widen Zendesk into a generic support administration proxy
• add bulk mutation or destructive ticket flows without review
• hide tenant or ticket targeting behind arbitrary route input

Current update strategy

For now, Zendesk updates are manual:

• update the Dock / Hub Zendesk integration document in apps/hub/catalog/integrations/zendesk/zendesk-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Official reference starting points

• Zendesk security and authentication: https://developer.zendesk.com/api-reference/introduction/security-and-auth/
• Zendesk tickets API overview: https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/
• List tickets: https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#list-tickets
• Show ticket: https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#show-ticket
• Create ticket: https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#create-ticket