# @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-` | | **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 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 5. Paste the Zendesk client id and client secret into the Kody wizard. 6. 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 3. 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`](./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 - [Zendesk REST API](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/) - [Security and authentication](https://developer.zendesk.com/api-reference/introduction/security-and-auth/) - [OAuth tokens](https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/) - [Help Center articles](https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/)