Zendesk

​

At a glance

npx @deploybaseline/cli start --service zendesk

import { createEmulator } from "@deploybaseline/cli";

const zendesk = await createEmulator({ service: "zendesk" });
// zendesk.url is http://localhost:4000

{
  "zendesk": {
    "subdomain": "acme",
    "owner": {
      "name": "Admin",
      "email": "[email protected]"
    },
    "groups": [
      {
        "name": "Tier 2"
      }
    ],
    "agents": [
      {
        "name": "Alex Agent",
        "email": "[email protected]",
        "groups": ["Support"]
      }
    ],
    "organizations": [
      {
        "name": "Globex",
        "domain_names": ["globex.example"]
      }
    ],
    "end_users": [
      {
        "name": "Casey Customer",
        "email": "[email protected]"
      }
    ],
    "api_tokens": [
      {
        "token": "baseline-zendesk-api-token",
        "description": "Local development"
      }
    ],
    "oauth_clients": [
      {
        "name": "My app",
        "identifier": "my_app",
        "secret": "my-app-secret",
        "redirect_uris": ["http://localhost:3000/zendesk/callback"]
      }
    ],
    "tickets": [
      {
        "subject": "Printer is on fire",
        "comment": "The printer in room 4 is smoking.",
        "requester": "[email protected]",
        "assignee": "[email protected]",
        "priority": "high",
        "tags": ["hardware"]
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service zendesk

import { createClient } from "node-zendesk";

const zendesk = createClient({
  username: "[email protected]",
  token: "baseline-zendesk-api-token",
  endpointUri: `${process.env.ZENDESK_EMULATOR_URL ?? "http://localhost:4000"}/api/v2`,
});

const { result: ticket } = await zendesk.tickets.create({
  ticket: { subject: "Printer is on fire", comment: { body: "Room 4 is smoking." }, priority: "urgent" },
});

​

URL mapping

​

Auth

• API token: Authorization: Basic base64("{email}/token:{api_token}") with a token from api_tokens[], for any active user’s email.
• Password: Authorization: Basic base64("{email}:{password}"), only when password_access: true. Seed passwords with owner.password, agents[].password, and end_users[].password.
• OAuth: Authorization: Bearer {access_token}. read covers every GET, write every change, and resource scopes such as tickets:read or users:write cover one resource.
• A token the CLI accepts (for example test_token_admin) sent as a bearer token acts as the account owner.

​

OAuth

• GET /oauth/authorizations/new?response_type=code&client_id=&redirect_uri=&scope=&state= shows the consent screen, where you choose the user to sign in as. code_challenge and code_challenge_method add PKCE, and response_type=token returns #access_token= (implicit grant)
• POST /oauth/tokens with JSON or a form: authorization_code (with client_secret, or a code_verifier), client_credentials (a confidential client acting as its owner), and refresh_token. Tokens do not expire unless the request sets expires_in (300 to 172800 seconds), which also returns a refresh token. Errors follow RFC 6749 (invalid_grant, invalid_client, unsupported_grant_type, invalid_scope)
• GET /api/v2/oauth/tokens, GET /api/v2/oauth/tokens/current, POST /api/v2/oauth/tokens (admins; answers full_token), GET and DELETE /api/v2/oauth/tokens/:id
• GET /api/v2/oauth/clients, POST /api/v2/oauth/clients, GET /api/v2/oauth/clients/:id, PUT /api/v2/oauth/clients/:id, DELETE /api/v2/oauth/clients/:id, and PUT /api/v2/oauth/clients/:id/generate_secret

​

Errors

​

Rate limits

​

Tickets

• GET /tickets, GET /tickets/count, GET /tickets/show_many?ids=, GET /tickets/:id
• POST /tickets answers 201 with ticket and audit. The first comment is required (Description: cannot be blank)
• PUT /tickets/:id with comment, status, priority, type, assignee_id, group_id, requester_id or requester: { email, name }, tags, additional_tags, remove_tags, custom_fields, due_at, problem_id, external_id, follower_ids, email_cc_ids, collaborator_ids, and safe_update with updated_stamp (409 UpdateConflict when the ticket changed)
• DELETE /tickets/:id soft deletes; GET /deleted_tickets, PUT /deleted_tickets/:id/restore, and DELETE /deleted_tickets/:id (a job) manage deleted tickets
• POST /tickets/create_many, PUT /tickets/update_many (?ids= with one ticket, or a tickets array with ids), and DELETE /tickets/destroy_many?ids= answer a job status. Jobs run at once; the creation answer says queued and GET /job_statuses/:id says completed with per item results and errors
• Tags: GET /tickets/:id/tags, POST replaces, PUT adds, DELETE removes
• GET /tickets/:id/collaborators, /followers, /email_ccs, /incidents, GET /problems
• GET /users/:id/tickets/requested, /ccd, /assigned, /followed, and GET /organizations/:id/tickets

​

Status lifecycle

• A new ticket with an assignee is open. A ticket cannot go back to new.
• Solving assigns the solving agent when no one is assigned, and offers a satisfaction rating.
• A comment from the requester reopens a pending, hold, or solved ticket.
• Solved tickets close solved_close_after_ms after they were solved (four days by default), through the “Close ticket 4 days after status is set to solved” automation. POST /_zendesk/simulate/close-solved with an optional {"ticket_ids": [...]} closes them now.
• Closed is terminal: updates answer 422 Status: closed prevents ticket update. Create a follow-up with via_followup_source_id.
• Solving a problem solves its incidents.
• Setting both group_id and an assignee_id outside that group is refused.

​

Custom fields

​

Comments

​

Satisfaction ratings

​

Users, organizations, and groups

• Users: list (role, role[]), count, me, search (query or external_id), autocomplete, show_many, create, create_many, create_or_update, create_or_update_many, show, update, delete (soft). A new user joins the organization whose domain_names match the email domain
• Identities: list, show, create, update, make_primary, verify, delete
• Tags on users and organizations: GET, POST replaces, PUT adds, DELETE removes. GET /tags and GET /autocomplete/tags list tags across the account
• Organizations: list, count, show_many, search (name or external_id), autocomplete, create, create_many, create_or_update, destroy_many, show, update, delete, and their users
• Organization memberships: list (all, per organization, per user), create, create_many, show, delete, and make_default
• Groups: list, count, assignable, create, show, update, delete (soft), and their users. Group memberships: list, assignable, create, create_many, show, delete, and make_default. Only agents and admins can be members

​

Pagination

​

Search

• Free text and "quoted phrases", - to negate, and * as a wildcard
• keyword:value, keyword<value, keyword>value, keyword<=value, keyword>=value
• type:ticket, type:user, type:organization, type:group (every type without one)
• Tickets: status and priority (ordered, so status<solved works), ticket_type, tags, subject, description, comment, assignee, requester, submitter, cc, follower, commenter (me, none, an id, an email, or a name), group, organization, via, external_id, satisfaction, fieldvalue, and the dates created, updated, solved, and due_date (2026-01-01, an ISO time, or a relative time such as 4hours or 2days)
• Users: name, email, role, organization, group, tags, phone, external_id, notes, details, is_verified, is_suspended
• Organizations: name, tags, domain, external_id, details, notes. Groups: name
• order_by: and sort: in the query, or sort_by and sort_order parameters

​

Views

​

Triggers

• Conditions: update_type (Create, Change), status, priority, type, group_id, assignee_id, requester_id, organization_id, current_tags, comment_is_public, comment_includes_word, subject_includes_word, role, via_id, and custom_fields_{id}, with is, is_not, less_than, greater_than, changed, not_changed, value, value_previous, includes, not_includes, present, and not_present
• Actions: status, priority, type, group_id, assignee_id (current_user works), set_tags, current_tags, remove_tags, custom_fields_{id}, and notification_webhook with [webhook_id, body]. The body takes placeholders such as {{ticket.id}}, {{ticket.title}}, {{ticket.status}}, {{ticket.url}}, {{ticket.requester.email}}, and {{current_user.name}}, escaped for JSON when the webhook sends JSON

​

Webhooks

• GET /webhooks (cursor pages, filter[name_contains], filter[status], sort), POST /webhooks (201), GET /webhooks/:id, PUT and PATCH /webhooks/:id (204), DELETE /webhooks/:id
• GET /webhooks/:id/signing_secret and POST /webhooks/:id/signing_secret (rotate)
• POST /webhooks/test sends a request and answers what the endpoint said. Without webhook_id it is signed with Zendesk’s static test secret dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==
• GET /webhooks/:id/invocations and GET /webhooks/:id/invocations/:invocation_id/attempts

import { createHmac } from "node:crypto";

const timestamp = req.headers["x-zendesk-webhook-signature-timestamp"];
const expected = createHmac("sha256", signingSecret).update(timestamp + rawBody).digest("base64");
const valid = expected === req.headers["x-zendesk-webhook-signature"];

​

Seed config

{
  "zendesk": {
    "subdomain": "acme",
    "password_access": true,
    "solved_close_after_ms": 345600000,
    "rate_limit": 700,
    "owner": {
      "name": "Admin",
      "email": "[email protected]",
      "password": "admin-password"
    },
    "groups": [
      {
        "name": "Tier 2"
      }
    ],
    "agents": [
      {
        "name": "Alex Agent",
        "email": "[email protected]",
        "groups": ["Support"],
        "password": "alex-password"
      },
      {
        "name": "Ada Admin",
        "email": "[email protected]",
        "role": "admin"
      }
    ],
    "organizations": [
      {
        "name": "Globex",
        "domain_names": ["globex.example"],
        "tags": ["enterprise"]
      }
    ],
    "end_users": [
      {
        "name": "Casey Customer",
        "email": "[email protected]"
      }
    ],
    "ticket_fields": [
      {
        "title": "Plan",
        "type": "tagger",
        "options": [
          {
            "name": "Free",
            "value": "plan_free"
          },
          {
            "name": "Pro",
            "value": "plan_pro"
          }
        ]
      },
      {
        "title": "Order number",
        "type": "integer"
      }
    ],
    "api_tokens": [
      {
        "token": "baseline-zendesk-api-token",
        "description": "Local development"
      }
    ],
    "oauth_clients": [
      {
        "name": "My app",
        "identifier": "my_app",
        "secret": "my-app-secret",
        "redirect_uris": ["http://localhost:3000/zendesk/callback"]
      }
    ],
    "oauth_tokens": [
      {
        "token": "baseline-zendesk-oauth-token",
        "user": "[email protected]",
        "scopes": ["read", "write"],
        "client": "my_app"
      }
    ],
    "webhooks": [
      {
        "name": "Ticket events",
        "endpoint": "http://localhost:3000/zendesk/webhooks",
        "subscriptions": ["zen:event-type:ticket.created", "zen:event-type:ticket.status_changed"],
        "signing_secret": "baseline-zendesk-secret"
      }
    ],
    "triggers": [
      {
        "title": "Tag urgent tickets",
        "conditions": {
          "all": [
            {
              "field": "priority",
              "operator": "is",
              "value": "urgent"
            }
          ]
        },
        "actions": [
          {
            "field": "current_tags",
            "value": "escalated"
          }
        ]
      }
    ],
    "views": [
      {
        "title": "Urgent",
        "all": [
          {
            "field": "priority",
            "operator": "is",
            "value": "urgent"
          }
        ]
      }
    ],
    "tickets": [
      {
        "subject": "Printer is on fire",
        "comment": "The printer in room 4 is smoking.",
        "requester": "[email protected]",
        "assignee": "[email protected]",
        "group": "Support",
        "priority": "high",
        "tags": ["hardware"],
        "custom_fields": [
          {
            "title": "Plan",
            "value": "plan_pro"
          }
        ],
        "comments": [
          {
            "author": "[email protected]",
            "body": "Looking into it.",
            "public": false
          }
        ]
      }
    ]
  }
}

​

Inspector

​

Limits

​

Conformance