@kody/zendesk
Call Zendesk tickets, users, and Help Center articles through OAuth or an API token.
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.
| Lane | When to use | Credential |
|---|---|---|
| OAuth (recommended) | Refresh tokens, scoped access, multi-account | Saved integration zendesk or zendesk-<purpose> |
| API token + email | Fastest for a single account | User 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
- In Admin Center open Apps and integrations → APIs → OAuth clients.
- Create a Confidential client.
- Set the redirect URI exactly to
https://kody.codes/connect/oauth. - 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
- Paste the Zendesk client id and client secret into the Kody wizard.
- 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
- Create a token at Apps and integrations → APIs → Zendesk API.
- 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
- 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
| Scope | Needed for |
|---|---|
tickets:read / tickets:write | Ticket reads / writes |
users:read / users:write | User reads / writes (incl. smoke) |
hc:read / hc:write | Help Center reads / writes |
read / write | Broad 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.comapproved - Subdomain available via call arg or
./configureon your fork - Smoke test returns
ok: true(livehasUserIdwhen credentials exist; no email) - Destructive helpers refuse unless
confirm: true;dryRun: truenever 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.