Zendesk OAuth local test playbook

This playbook reproduces the local Zendesk OAuth validation used for the OpenCX Zendesk integration. It covers a fresh install, an existing legacy customer switching to OAuth, OAuth-only operation, same-account fallback, cross-account isolation, inbound messaging, replies, media, handoff, Agent Workspace, closing and reopening, uninstall, and reinstall. Use a Zendesk development account and a disposable OpenCX organization. Do not run destructive lifecycle steps against a customer account.

What must pass

Product	Authorization	Required behavior
Ticketing	Legacy	Existing email, API token, webhook, ticket, and public-reply flows remain unchanged.
Ticketing	OAuth	Fresh connection creates usable ticketing settings, derives the default agent from the authorizing Zendesk user, and performs ticket/user/group/Guide/webhook operations without an API token.
Ticketing	Hybrid	OAuth is preferred. A revoked OAuth grant is fenced and the failing operation retries once with complete same-account legacy credentials.
Ticketing	Account mismatch	Legacy credentials from a different subdomain are never used as fallback.
Messaging	Legacy	Existing Sunshine App key, webhook, switchboard, inbound message, and handoff flows remain unchanged.
Messaging	OAuth	A fresh Marketplace install provisions an encrypted token and signed webhook, then supports inbound messages, deduplication, media, replies, handoff, close, and reopen.
Messaging	Hybrid	OAuth is preferred. Revoked OAuth retries the same operation once with complete same-account App credentials and marks OAuth for reconnect.
Messaging	Account mismatch	One Marketplace app is owned by one OpenCX organization; another org or subdomain fails closed.
Lifecycle	Both	State is bound to org, user, and browser session; replay is rejected; disconnect cancels outstanding callbacks; legacy credentials survive OAuth disconnect.
Uninstall	Messaging	A genuine Zendesk uninstall removes the OAuth installation locally, preserves legacy credentials, and permits a clean reinstall.

Prerequisites

Node.js 24.
Docker and the services in backend/docker-compose.yml.
cloudflared for a public webhook origin.
Google Chrome for the local full-stack browser test.
A Zendesk development account with Support, Messaging, Agent Workspace, a Web Widget channel, and admin access.
An approved OpenCX Marketplace bot for Messaging OAuth.
An approved Zendesk global OAuth client for Ticketing OAuth. URL-construction tests can run with a test client ID, but successful consent requires the real approved client.
An OpenCX development user with owner/admin access to a disposable organization.

Keep credentials out of files

Never paste OAuth secrets, access tokens, callback codes, signed webhook URLs, widget keys, or Zendesk passwords into this document, a shell history entry, a test file, a commit, or CI output. Store local secrets in macOS Keychain and expose them only to the process that needs them. For example:

security add-generic-password -U \
  -s opencx-zendesk-ticketing-oauth-secret \
  -a "$USER" \
  -w

security add-generic-password -U \
  -s opencx-zendesk-sunshine-oauth-secret \
  -a "$USER" \
  -w

Load values without printing them:

export ZENDESK_TICKETING_OAUTH_CLIENT_SECRET="$(security find-generic-password -w -s opencx-zendesk-ticketing-oauth-secret -a "$USER")"
export ZENDESK_SUNSHINE_OAUTH_CLIENT_SECRET="$(security find-generic-password -w -s opencx-zendesk-sunshine-oauth-secret -a "$USER")"

The backend uses these variables:

export ZENDESK_TICKETING_OAUTH_CLIENT_ID='<approved-global-client-id>'
export ZENDESK_TICKETING_OAUTH_CLIENT_SECRET='<from-keychain>'
export ZENDESK_SUNSHINE_OAUTH_CLIENT_ID='<approved-marketplace-client-id>'
export ZENDESK_SUNSHINE_OAUTH_CLIENT_SECRET='<from-keychain>'
export ZENDESK_MARKETPLACE_NAME='<marketplace-name>'
export ZENDESK_MARKETPLACE_ORGANIZATION_ID='<marketplace-organization-id>'
export ZENDESK_MARKETPLACE_BOT_ID='<marketplace-bot-id>'
export ZENDESK_OAUTH_REDIRECT_DASHBOARD_BASE_URL='http://localhost:3000'

Use literal values in backend/.env only when that ignored file is already the team’s approved local secret store. Never add it to Git.

Prepare the worktree

Run every command from the OAuth PR worktree, not a different checkout:

cd /path/to/opencx-oauth-worktree
git branch --show-current
git status --short
node --version

The branch must be the Zendesk OAuth PR branch and Node must report v24.x. Install dependencies separately because backend and dashboard pin different pnpm versions:

cd backend
corepack pnpm install --frozen-lockfile

cd ../dashboard
corepack pnpm install --frozen-lockfile

If a private @opencx-labs/* package returns 401 or 403, repair the Keychain-backed GitHub Packages token first. Do not share another worktree’s node_modules; cross-worktree symlinks caused the incorrect local font and incomplete dependency tree seen during the original validation.

Start local infrastructure

cd backend
docker compose up -d
pnpm dev:prepare

The required local ports are:

Service	Port
Dashboard	`3000`
Backend	`8080`
Zendesk webhook proxy	`18080`
Static widget page	`18081`
PostgreSQL	`5432`
Redis	`6379`

Create a narrow public webhook proxy

Do not tunnel the entire local backend. The proxy below exposes only the signed Zendesk webhook route and Marketplace uninstall route, while capturing the latest event for the live test. Create /tmp/opencx-zendesk-webhook-proxy.mjs:

import http from "node:http";
import { writeFileSync } from "node:fs";

const webhookPrefix = "/backend/zendesk/webhook/";
const uninstallPath = "/backend/zendesk-sunshine-oauth/uninstall";

http
  .createServer(async (request, response) => {
    if (request.method === "HEAD") {
      response.writeHead(200);
      response.end();
      return;
    }

    const allowed =
      request.method === "POST" &&
      (request.url?.startsWith(webhookPrefix) || request.url === uninstallPath);
    if (!allowed) {
      response.writeHead(404);
      response.end();
      return;
    }

    const chunks = [];
    for await (const chunk of request) chunks.push(chunk);
    const body = Buffer.concat(chunks);
    if (request.url?.startsWith(webhookPrefix)) {
      writeFileSync("/tmp/opencx-last-zendesk-webhook.json", body, { mode: 0o600 });
    }

    const upstream = http.request(
      {
        host: "127.0.0.1",
        port: 8080,
        method: request.method,
        path: request.url,
        headers: request.headers,
      },
      (upstreamResponse) => {
        response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
        upstreamResponse.pipe(response);
      },
    );
    upstream.on("error", () => {
      if (!response.headersSent) response.writeHead(502);
      response.end();
    });
    upstream.end(body);
  })
  .listen(18080, "127.0.0.1");

Start it and the tunnel:

node /tmp/opencx-zendesk-webhook-proxy.mjs
cloudflared tunnel --url http://127.0.0.1:18080

Copy only the generated HTTPS origin, without a trailing slash:

export SERVER_BASE_URL='https://<generated-host>.trycloudflare.com'

Start the backend after SERVER_BASE_URL is set. The OAuth callback uses it to provision the real Zendesk webhook target.

cd backend
pnpm ddev

Confirm the public proxy is narrow:

curl -I "$SERVER_BASE_URL/"

A HEAD request returns success for tunnel health. An unrelated GET or POST path must return 404.

Start the dashboard

Set the local backend URL in dashboard/.env:

VITE_BACKEND_URL=http://localhost:8080

Then start the dashboard:

cd dashboard
pnpm xdev

Open http://localhost:3000/auth, use Dev login, select the disposable org, then open Settings → Integrations → Zendesk. The first page must show exactly two product choices: Zendesk Ticketing and Zendesk Messaging. Selecting a product must show exactly two authorization choices: OAuth and Legacy credentials. OAuth carries the New and Recommended badges. This test uses the real local backend and system Chrome without downloading a Playwright browser revision:

cd dashboard
PLAYWRIGHT_USE_SYSTEM_CHROME=1 \
E2E_WITH_BACKEND=1 \
E2E_ZENDESK_OAUTH_START=1 \
VITE_BACKEND_URL=http://localhost:8080 \
node_modules/.bin/playwright test \
  e2e/zendesk-oauth-setup.e2e.ts \
  --project=chromium \
  --reporter=list

It verifies the two-stage selector, both Legacy forms, both OAuth panels, invalid Ticketing subdomains, real start URL construction, callback-error routing, status isolation, the Ticketing reply webhook, and trigger-instructions link.

Ticketing OAuth: Zendesk-side setup

In OpenCX choose Zendesk → Ticketing → OAuth.
Enter only the Zendesk subdomain, such as acme.
Click Continue to Zendesk.
Confirm the Zendesk hostname matches the entered subdomain.
Sign in as an agent or admin and click Allow.
Confirm OpenCX returns to the OAuth panel with Connected and the correct subdomain.
Copy the signed Reply webhook URL shown in the panel.
In Zendesk Admin Center open Apps and integrations → Webhooks and create a POST JSON webhook with no extra authentication.
Open Objects and rules → Triggers and create the following trigger:
- Meet ANY: Ticket is Created; Ticket is Updated.
- Meet ALL: Comment is Present (public).
- Action: notify the OpenCX active webhook.
- Body:

{
  "ticketId": "{{ticket.id}}",
  "event_type": "new_comment"
}

OAuth authenticates OpenCX’s outbound Support API calls. The classic trigger is independently required for inbound public-comment delivery. Never put comment text in the webhook body; OpenCX fetches and filters public comments itself. If the global client has not yet been approved, stop after the automated start-URL test. A test client ID can prove URL construction but cannot prove consent, token exchange, or refresh rotation.

Messaging OAuth: Zendesk-side setup

In OpenCX choose Zendesk → Messaging → OAuth and click Continue to Zendesk.
Zendesk opens the OpenCX Marketplace bot authorization. Click Allow once.
For a local backend, Zendesk may redirect to the registered production callback origin. Before that callback is consumed, replace only the origin with http://localhost:8080, preserving /backend/zendesk-sunshine-oauth/callback and the entire query string byte-for-byte. Do not reload or reuse a callback code.
Confirm the local callback returns to http://localhost:3000/settings/integrations and shows Connected.
In Zendesk Admin Center open AI → AI agents → AI agents → Marketplace bots → OpenCX.
Assign OpenCX to one disposable Web Widget or staging channel and save.
In Channels → Messaging and social → Messaging, make OpenCX the test channel’s default responder.
Set Conversation control to Release control so a closed Agent Workspace conversation returns to OpenCX on the next customer message.

The OAuth callback automatically provisions the integration-scoped webhook. Do not manually create a second Sunshine webhook for the OAuth path. Get the test channel’s Web Widget key from Zendesk Admin Center, then create /tmp/opencx-zendesk-widget.html without committing it:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>OpenCX Zendesk OAuth live test</title>
  </head>
  <body>
    <h1>OpenCX Zendesk OAuth live test</h1>
    <script
      id="ze-snippet"
      src="https://static.zdassets.com/ekr/snippet.js?key=<WEB_WIDGET_KEY>"
    ></script>
  </body>
</html>

Serve and open it:

python3 -m http.server 18081 --directory /tmp
open http://localhost:18081/opencx-zendesk-widget.html

Send a unique message such as OAuth live inbound <UUID>. Wait for /tmp/opencx-last-zendesk-webhook.json, then extract the live values without printing the whole webhook:

export ZENDESK_SUNSHINE_LIVE_CONVERSATION_ID="$(jq -r '.events[0].payload.conversation.id' /tmp/opencx-last-zendesk-webhook.json)"
export ZENDESK_SUNSHINE_LIVE_INBOUND_TEXT="$(jq -r '.events[0].payload.message.content.text' /tmp/opencx-last-zendesk-webhook.json)"
export ZENDESK_SUNSHINE_LIVE_ORG_ID='<disposable-opencx-org-id>'

Run the real Messaging OAuth lifecycle

CI_SKIP_FLAKY_TESTS must be absent. Setting it to false still skips tests because any nonempty value is truthy in the test environment.

cd backend
env -u CI_SKIP_FLAKY_TESTS \
  ZENDESK_SUNSHINE_LIVE_ORG_ID="$ZENDESK_SUNSHINE_LIVE_ORG_ID" \
  ZENDESK_SUNSHINE_LIVE_CONVERSATION_ID="$ZENDESK_SUNSHINE_LIVE_CONVERSATION_ID" \
  ZENDESK_SUNSHINE_LIVE_INBOUND_TEXT="$ZENDESK_SUNSHINE_LIVE_INBOUND_TEXT" \
  pnpm test \
    src/zendesk-integration/sunshine/__tests__/sunshine-oauth-marketplace-live-lifecycle.e2e.spec.ts \
    --reporter=verbose

The test proves:

the active auth is a Marketplace bearer;
the database value is encrypted at rest;
Zendesk has the expected signed webhook target;
the real inbound webhook created a contact, session, conversation mapping, and history row;
replaying the captured webhook does not duplicate the inbound message;
an OpenCX business reply and image reach the real Zendesk conversation;
handoff transfers switchboard control to zd:agentWorkspace;
a post-handoff OpenCX agent reply reaches Zendesk and remains one local agent message.

Manual Agent Workspace and reopen checks

After the live spec:

Open the real conversation in Zendesk Agent Workspace.
Send a unique public agent reply.
Confirm the customer sees it in the Web Widget and OpenCX stores it once as an agent message.
Solve and close the Agent Workspace conversation.
Confirm the OpenCX session closes and the Zendesk ticket reaches the expected terminal state.
Send another unique customer message from the widget.
Confirm routing returns to OpenCX, a new OpenCX session is created, and the new lifecycle does not append to the sealed session.

Legacy, hybrid, and isolation regressions

Run the focused real Zendesk matrix with flaky skipping unset:

cd backend
env -u CI_SKIP_FLAKY_TESTS VITEST_MAX_WORKERS=1 pnpm test \
  src/zendesk-integration-v2/__tests__/oauth-e2e/real-oauth-ticket-lifecycle.e2e.spec.ts \
  src/zendesk-integration-v2/__tests__/oauth-e2e/real-basic-auth-org-unaffected-by-oauth-support.e2e.spec.ts \
  src/zendesk-integration-v2/__tests__/oauth-e2e/real-oauth-revoked-api-request-context-falls-back-to-basic.e2e.spec.ts \
  src/zendesk-integration-v2/__tests__/oauth-e2e/real-oauth-revoked-api-request-context-fails-closed.e2e.spec.ts \
  src/zendesk-integration-v2/__tests__/oauth-e2e/real-oauth-revoked-webhook-provisioning-falls-back-to-basic.e2e.spec.ts \
  src/zendesk-integration/sunshine/__tests__/get-zendesk-ticketing-creds-cross-store-revoked-oauth-falls-back-to-basic.e2e.spec.ts \
  src/livekit-voice-agent/__tests__/contact-enrichment.revoked-oauth.real-zendesk.spec.ts \
  --reporter=verbose

Then run the local DB/HTTP defensive matrix:

pnpm test \
  src/zendesk-integration-v2/__tests__/zendesk-ticketing-oauth-callback-rejects-different-user.spec.ts \
  src/zendesk-integration-v2/__tests__/zendesk-ticketing-oauth-callback-rejects-different-user-org.spec.ts \
  src/zendesk-integration-v2/__tests__/zendesk-ticketing-oauth-callback-rejects-different-session.spec.ts \
  src/zendesk-integration-v2/__tests__/zendesk-ticketing-oauth-disconnect-cancels-callback.spec.ts \
  src/zendesk-integration/sunshine/__tests__/sunshine-oauth-concurrent-app-claim-has-one-owner.spec.ts \
  src/zendesk-integration/sunshine/__tests__/sunshine-oauth-lifecycle-generation.spec.ts \
  src/zendesk-integration/sunshine/__tests__/sunshine-oauth-stale-401-does-not-poison-current-token.spec.ts \
  src/zendesk-integration/sunshine/__tests__/sunshine-oauth-expired-hybrid-falls-back-to-legacy.spec.ts \
  --reporter=verbose

Uninstall and reinstall

Zendesk’s Marketplace uninstall callback is unauthenticated. OpenCX accepts cleanup only after the stored bearer proves revoked. Therefore:

Remove the OpenCX Marketplace bot through Zendesk first.
Wait for Zendesk’s Remove URL callback.
If the saved Remove URL points to production and cannot reach the local backend, replay the same uninstall notification to the local public tunnel only after the real Zendesk removal has revoked the bearer:

curl -X POST "$SERVER_BASE_URL/backend/zendesk-sunshine-oauth/uninstall" \
  -H 'content-type: application/json' \
  --data '{"appId":"<installed-app-id>","integrationId":"<zendesk-integration-id>"}'

Confirm Messaging OAuth status is disconnected.
Confirm any Legacy Sunshine credentials still exist and remain usable.
Confirm an OAuth-only org no longer routes through Zendesk when neither Ticketing nor Legacy Sunshine auth remains.
Start Messaging OAuth again, click Allow, reassign the bot to the staging channel, and confirm a new inbound message works.

Never send the uninstall callback while the bearer is active. OpenCX must retain the connection because an active bearer means the callback is forged or stale.

Final verification before pushing

cd backend
pnpm tsgo
pnpm voice:test

cd ../dashboard
pnpm type-check

cd ..
git diff --check

Also run scoped formatter and linter checks for every changed backend, dashboard, test, and docs file. Review the entire diff, then run an independent PR review before committing. The completion record should include:

exact test commands and pass counts;
proof that CI_SKIP_FLAKY_TESTS was unset for live tests;
the test Zendesk subdomain and disposable OpenCX org, but no secrets;
confirmation that the installed token was encrypted at rest;
confirmation that webhook replay deduplicated;
confirmation that Agent Workspace reply, close, reopen, uninstall, and reinstall worked;
CI and reviewer status on the pushed PR.

Troubleshooting

`Partner in query parameter 'client_id' not found`

The Marketplace client ID is not approved, not published to the selected Zendesk environment, or does not match ZENDESK_SUNSHINE_OAUTH_CLIENT_ID. This is a Zendesk Marketplace registration problem, not a customer API-token problem. Confirm the global OAuth client is approved for the exact client ID and callback URL. A tenant-local OAuth client cannot behave as the global client used by this integration.

Callback lands on `api.open.cx` during local testing

Before consuming the one-time callback, replace only the origin with http://localhost:8080. Preserve the path, code, state, and encoding. Never paste the callback URL into logs or a ticket.

Callback says state is invalid or expired

Start a new OAuth flow in the same authenticated browser session. State is intentionally one-time, short-lived, and bound to the exact OpenCX user, org, and session.

No Messaging webhook arrives

Check all of the following:

backend started after SERVER_BASE_URL was set to the current tunnel;
the Marketplace bot is assigned to the test channel;
the channel’s default responder is OpenCX;
the OAuth status is connected and does not require reconnect;
the public proxy receives only the expected signed webhook path;
Conversation control is set to Release control for return routing.

Ticketing agent replies do not return to OpenCX

OAuth does not replace the Zendesk trigger. Confirm the signed Reply webhook URL, POST JSON webhook, Created-or-Updated public-comment trigger, and exact ticketId/event_type body.

Dashboard font or components look different from production

Verify the dashboard uses branch-local dependencies. Remove a broken node_modules symlink and reinstall with the correct dashboard pnpm version and a working private-package token. The expected UI font is Inter.

A real test is reported as skipped

Run it with env -u CI_SKIP_FLAKY_TESTS. Do not set the variable to false.

AI reply assertions fail with an OpenRouter authentication error

Repair the local OpenRouter test credential. That error is independent of Zendesk OAuth and should not be hidden by changing OAuth expectations.

Cleanup

Delete every temporary Zendesk ticket, user, webhook, trigger, and channel assignment created by the run.
Leave the Marketplace bot installed only if the disposable org is intended to remain connected; otherwise uninstall it through Zendesk and verify local cleanup.
Stop dashboard, backend, widget server, webhook proxy, and cloudflared.
Remove only these explicit temporary files:

rm /tmp/opencx-zendesk-webhook-proxy.mjs
rm /tmp/opencx-zendesk-widget.html
rm /tmp/opencx-last-zendesk-webhook.json

Stop Docker services when they are no longer needed:

cd backend
docker compose down

Do not delete shared development databases, volumes, credentials, or another worktree’s dependencies as part of cleanup.

Overview

Ticketing Systems

E-commerce

Other Integrations

Local test playbook

Zendesk OAuth local test playbook

What must pass

Prerequisites

Keep credentials out of files

Prepare the worktree

Start local infrastructure

Create a narrow public webhook proxy

Start the dashboard

Ticketing OAuth: Zendesk-side setup

Messaging OAuth: Zendesk-side setup

Create the local Web Widget page

Run the real Messaging OAuth lifecycle

Manual Agent Workspace and reopen checks

Legacy, hybrid, and isolation regressions

Uninstall and reinstall

Final verification before pushing

Troubleshooting

`Partner in query parameter 'client_id' not found`

Callback lands on `api.open.cx` during local testing

Callback says state is invalid or expired

No Messaging webhook arrives

Ticketing agent replies do not return to OpenCX

Dashboard font or components look different from production

A real test is reported as skipped

AI reply assertions fail with an OpenRouter authentication error

Cleanup

​Zendesk OAuth local test playbook

​What must pass

​Prerequisites

​Keep credentials out of files

​Prepare the worktree

​Start local infrastructure

​Create a narrow public webhook proxy

​Start the dashboard

​Run the full-stack modal test

​Ticketing OAuth: Zendesk-side setup

​Messaging OAuth: Zendesk-side setup

​Create the local Web Widget page

​Run the real Messaging OAuth lifecycle

​Manual Agent Workspace and reopen checks

​Legacy, hybrid, and isolation regressions

​Uninstall and reinstall

​Final verification before pushing

​Troubleshooting

​Partner in query parameter 'client_id' not found

​Ticketing authorize URL opens but consent fails

​Callback lands on api.open.cx during local testing

​Callback says state is invalid or expired

​No Messaging webhook arrives

​Ticketing agent replies do not return to OpenCX

​Dashboard font or components look different from production

​A real test is reported as skipped

​AI reply assertions fail with an OpenRouter authentication error

​Cleanup

Zendesk OAuth local test playbook

What must pass

Prerequisites

Keep credentials out of files

Prepare the worktree

Start local infrastructure

Create a narrow public webhook proxy

Start the dashboard

Run the full-stack modal test

Ticketing OAuth: Zendesk-side setup

Messaging OAuth: Zendesk-side setup

Create the local Web Widget page

Run the real Messaging OAuth lifecycle

Manual Agent Workspace and reopen checks

Legacy, hybrid, and isolation regressions

Uninstall and reinstall

Final verification before pushing

Troubleshooting

`Partner in query parameter 'client_id' not found`

Ticketing authorize URL opens but consent fails

Callback lands on `api.open.cx` during local testing

Callback says state is invalid or expired

No Messaging webhook arrives

Ticketing agent replies do not return to OpenCX

Dashboard font or components look different from production

A real test is reported as skipped

AI reply assertions fail with an OpenRouter authentication error

Cleanup