Skip to content
← Public packages

@kody/zendesk

Call Zendesk tickets, users, and Help Center articles through OAuth or an API token.

FollowFork

OtherTopics: zendesk, tickets, users, articles, help-center, oauth, api-token, dry-run

Version
1.0.0
License
MIT
Published
September 10, 2026
Pinned commit
68dd4c2
Rating
No ratings yet
Forks
0
Adaptation effort
—

README

Agent docs

@kody/zendesk

Intent

Provide reusable, account-agnostic Zendesk helpers so Kody agents can read and update tickets, users, and Help Center articles through a saved zendesk / zendesk-* OAuth integration or an API token plus agent email — without hand-rolling REST. The Support subdomain is an input (or packageStorage config.subdomain) so this package is not locked to one account. Mutations are previewable with dryRun: true and only run live after confirm: true.

This listing is meant to be forked. After you fork, connect your Zendesk account. Do not treat the live @kody/zendesk package storage as yours.

Share: https://kody.codes/@kody/zendesk

What it does

  • List, search, or inspect tickets, ticket comments, users, and Help Center articles
  • Create or update tickets, users, and articles after explicit confirmation
  • Call an unwrapped Zendesk REST path through ./request
  • Connect more than one Zendesk account via integrationName / account

Prerequisites / setup

Zendesk has no built-in Kody OAuth app. Choose one lane. Both need your Support subdomain (acme from https://acme.zendesk.com). Pass subdomain on each call, or store it once with ./configure on your fork.

LaneWhen to useCredential
OAuth (recommended)Refresh tokens, scoped access, multi-accountSaved integration zendesk or zendesk-<purpose>
API token + emailFastest for a single accountUser secrets zendeskApiUsername ({email}/token) and zendeskApiToken

Required API host: {your-subdomain}.zendesk.com. Approve it in the account secrets UI. Never paste tokens into chat.

Lane A — BYO OAuth

  1. In Admin Center open Apps and integrations → APIs → OAuth clients.
  2. Create a Confidential client.
  3. Set the redirect URI exactly to https://kody.codes/connect/oauth.
  4. Connect while signed in to Kody (replace your-subdomain):

https://kody.codes/connect/oauth?provider=zendesk&authorizeUrl=https%3A%2F%2Fyour-subdomain.zendesk.com%2Foauth%2Fauthorizations%2Fnew&tokenUrl=https%3A%2F%2Fyour-subdomain.zendesk.com%2Foauth%2Ftokens&apiBaseUrl=https%3A%2F%2Fyour-subdomain.zendesk.com%2Fapi%2Fv2&scopes=read%20write%20tickets%3Aread%20tickets%3Awrite%20users%3Aread%20users%3Awrite%20hc%3Aread%20hc%3Awrite&flow=confidential&pkce=false&allowedHosts=your-subdomain.zendesk.com&dashboardUrl=https%3A%2F%2Fyour-subdomain.zendesk.com%2Fadmin%2Fapps-integrations%2Fapis%2Foauth_clients

  1. Paste the Zendesk client id and client secret into the Kody wizard.
  2. Reconnect later: https://kody.codes/connect/oauth?provider=zendesk

For a second account, change provider (for example provider=zendesk-work) and pass integrationName: 'zendesk-work' plus that account's subdomain.

Lane B — API token + email

  1. Create a token at Apps and integrations → APIs → Zendesk API.
  2. Save the Basic username {agent-email}/token:

https://kody.codes/account/secrets/new?name=zendeskApiUsername&description=Zendesk%20API%20username%20(your-agent-email%2Ftoken)&allowedHosts=your-subdomain.zendesk.com&scope=user

  1. Save the API token:

https://kody.codes/account/secrets/new?name=zendeskApiToken&description=Zendesk%20API%20token%20from%20Admin%20Center%20%E2%86%92%20Zendesk%20API&allowedHosts=your-subdomain.zendesk.com&scope=user

Scopes

ScopeNeeded for
tickets:read / tickets:writeTicket reads / writes
users:read / users:writeUser reads / writes (incl. smoke)
hc:read / hc:writeHelp Center reads / writes
read / writeBroad access when granular scopes are unavailable

Mutation safety

Mutating helpers require confirm: true. Pass dryRun: true to preview. The account-health job is disabled by default. Agents: import paths, smoke snippets, and confirm examples live in AGENTS.md.

Done when

  • OAuth connected or API token + username secrets saved; {subdomain}.zendesk.com approved
  • Subdomain available via call arg or ./configure on your fork
  • Smoke test returns ok: true (live hasUserId when credentials exist; no email)
  • Destructive helpers refuse unless confirm: true; dryRun: true never writes

Branding

The community icon is Zendesk's official Z symbol (the four-shape mark published in Zendesk brand resources / Simple Icons). Paths are unmodified. Fill is Zendesk Green Kelp #03363D. Zendesk® is a trademark of Zendesk, Inc.

Docs

Report this listing

Log in to report this listing.