Zendesk Marketplace

This guide defines the Zendesk Marketplace path after Slack Marketplace, the Zapier public integration scaffold, Microsoft Teams Store scoping, Google Workspace Marketplace scoping, and Atlassian Marketplace scoping. It is a design and launch-control document, not evidence that a Zendesk Marketplace app or integration has been built or approved.

Current Status

Zendesk Marketplace is planned as a public store follow-on. Threada has governed Zendesk action proposal payloads for zendesk_create_ticket and zendesk_update_ticket in the public API action model, and the shared Marketplace OAuth install path now supports a Zendesk global-OAuth install for one target subdomain with tenant-scoped Secret Manager credential storage. A private Zendesk integration-app package scaffold exists at packages/zendesk-marketplace-app. It generates a marketingOnly: true Marketplace source package, English content, asset checklist, listing metadata, and readiness blockers. Public setup/support guidance now lives in Zendesk setup and support.

No Zendesk Marketplace organization, developer profile, portal listing, global OAuth approval in Zendesk’s portal, real Marketplace organization/app identifiers, real brand assets, ZCLI/source-ZIP validation, reviewer setup evidence, sponsored test-account evidence, ticket-creation self-test, Marketplace request-header self-test, listing approval, or Zendesk review approval has been observed in this repository.

Do not submit a public Zendesk Marketplace listing until the chosen Zendesk app or integration package is built, installable or reviewer-exercisable in a reviewer-safe Zendesk account, validated end to end, linked to a Marketplace submission, and supported by reviewer setup evidence.

Do not market or claim Zendesk Marketplace readiness until Zendesk review has accepted the submitted app or integration.

The existing Zendesk action payloads remain tenant-specific governed action work. They should not be described as the public Zendesk Marketplace app.

Recommended V1

The enterprise-safe first package is the committed narrow Zendesk integration app scaffold for a governed Zendesk ticket-creation flow from a Threada WorkItem or customer request. Ticket creation aligns with the live zendesk_create_ticket action proposal payload and avoids starting with broad ticket updates, macros, bulk operations, help center sync, sell/chat surfaces, or autonomous AI ticketing-agent positioning.

Use a Zendesk Support app later only if reviewers or customers need an installable Zendesk Agent Workspace surface, such as a sidebar, top bar, nav bar, or ticket-action entry point. The committed v1 uses the Zendesk integration-app path with marketingOnly: true because the initial public listing can be discoverable while the executable Threada flow lives outside Zendesk. Any server-side Zendesk API calls for multiple customers must use Zendesk’s global OAuth posture and Marketplace request headers once the required Marketplace identifiers exist.

Ticket update and comment capability can follow only after the create-ticket flow is installed, reviewable, scoped, idempotent, audited, and accepted. Public copy must avoid autonomous AI ticketing-agent claims unless Threada supports the Zendesk requirements for all standard ticketing channels, complete end-user and bot message history, end-user attribution, and dedicated bot-agent messaging.

Positioning

Threada for Zendesk should help support teams turn governed Threada work into reviewable Zendesk ticket operations without bypassing policy, approval, idempotency, and audit controls.

The narrow v1 app should stay focused:

Install or discover Threada through a Zendesk Marketplace-reviewed app or integration app package.
Bind the Zendesk subdomain or account to a Threada tenant, pack, queue, or workspace mapping.
Create a Zendesk ticket only from a governed Threada action proposal.
Show clear setup-required, approval-pending, succeeded, and failed states in Threada and, when using a ZAF app, in the Zendesk app surface.
Provide public setup/support documentation that explains least-privilege Zendesk access, global OAuth, request headers, disconnect, and data handling.

The v1 app must not claim that Zendesk can execute arbitrary third-party actions through Threada. Direct external execution remains inside Threada’s governed Work, Studio, MCP, A2A, or first-party runtime paths.

Source Of Truth

Do not duplicate request or response schemas in this document. Public WorkItem shape and governed action proposal behavior are documented in Threada Public API and its generated OpenAPI artifact at /openapi/public-api.openapi.yaml. The committed source copy is docs/developers/public-api.openapi.yaml.

The private package source lives in packages/zendesk-marketplace-app. pnpm --filter @threada/zendesk-marketplace-app zendesk:package generates ignored local artifacts under packages/zendesk-marketplace-app/dist/, including:

zendesk-marketplace-config.json
source/manifest.json
source/translations/en.json
source/assets/README.md
source/threada-zendesk-integration-app.zip
marketplace-listing.json
readiness.json

When the real submission exists, the Zendesk Marketplace developer portal submission, source ZIP, generated manifest, translations/en.json, real brand assets, global OAuth client, Marketplace request-header configuration, install/disconnect behavior, tenant mapping, reviewer setup notes, and Zendesk approval result must become the source of truth for the public listing. The public setup/support URL for the package is https://docs.threada.ai/integrations/zendesk-setup/. The public Threada install handoff is https://studio.threada.ai/integrations/zendesk/install; append ?subdomain=<zendesk-subdomain> when a reviewer-safe Zendesk subdomain is known, or let Studio route to connector setup when it is not.

App Surface

Governed Ticket Creation

The first reviewable capability should create a Zendesk ticket from a Threada WorkItem or customer request. The implementation should use the chosen Zendesk Marketplace app path, then let Threada create a governed action proposal that writes to Zendesk only after the configured policy and approval path permits it.

Inputs should map to the live zendesk_create_ticket payload fields for subject, description, priority, requester_email, requester_name, and tags. Priority, requester attribution, tags, and any custom fields should be allowlisted or tenant-configured so the public app cannot create noisy or misattributed tickets.

Server-side Zendesk API requests for a multi-customer public app must use a Zendesk global OAuth client. Do not use customer API tokens, regular OAuth tokens, or manually provisioned tenant secrets as the public Marketplace install path. When Zendesk provides the Marketplace organization and app identifiers, external Zendesk API requests must include Zendesk’s Marketplace request headers.

Outputs must give the Threada user a clear success, setup-required, approval-pending, or failed state and preserve the Zendesk ticket reference when one is returned. Do not return only a generic success message; reviewers need to see the install-to-action-to-ticket journey.

Ticket Update And Comment Follow-On

Threada already exposes a governed payload type for Zendesk ticket update. A Zendesk Marketplace listing can reference update or comment capability only after the public Zendesk app proves the required OAuth posture, request headers, field allowlists, collision protection, public/private comment behavior, idempotency, audit behavior, reviewer flow, and Zendesk review evidence.

Inputs should map to the live zendesk_update_ticket payload fields for external_ticket_id, status, and comment. Zendesk comments are created through the Tickets API, so public copy and reviewer notes must distinguish ticket update behavior from a standalone comment API. The app must make public/private comment behavior explicit before any comment-writing capability is marketed.

Setup And Tenant Mapping

The app must bind a Zendesk subdomain or account to a Threada tenant, pack, queue, or workspace mapping before claiming production readiness. If setup is incomplete, Threada should show a clear setup-required response instead of silently dropping the request or attempting an unauthenticated Zendesk write.

Reviewer setup notes must include the exact Zendesk test subdomain or sponsored test account, Zendesk test user, Threada tenant, test pack or queue, install URL or Marketplace preview URL, expected ticket fields, and cleanup instructions. Credentials, tokens, cookies, raw ticket exports, requester PII, and customer data must stay out of repo evidence and screenshots.

Marketplace Package Requirements

Zendesk’s Marketplace documentation routes public apps and integration apps through a Marketplace developer portal submission, build/test work in a Zendesk Support account, global OAuth setup for multi-customer server-side API access, branding and content assets, source ZIP upload, automated checks, and Zendesk review. Zendesk also requires Marketplace request headers for external Zendesk API requests, ZCLI supports local validate/package flows, Zendesk app best practices call for secure settings, domain allowlists, app versions, cleanup, and removing console/debug statements, and server-side apps should use signed URLs/JWT validation where required.

Required package work before submission:

Decide whether v1 is an installable Zendesk Support app or a Zendesk integration app with marketingOnly: true.
For an installable app, create a Zendesk app package with manifest.json, private: false, supported locations, ZAF SDK integration, production URLs, and a validated source ZIP.
For an integration app, create the minimal integration-app package with marketingOnly: true, private: false, required translations and assets, and the server-side integration/install path that reviewers can exercise.
Use ZCLI to validate and package the app, then upload the source ZIP in the Marketplace developer portal.
Pass the Marketplace portal’s automated source ZIP checks and keep the reviewer-safe package free of debug statements, private credentials, and customer data.
Add required brand assets in the package assets directory, including logo.png, logo-small.png, and three full-bleed screenshots.
Add translations/en.json content for app name, short description, long description, and installation instructions. Include data disclosure details in the long description or privacy notice.
Register the Marketplace organization and developer profile, listing categories, support URL, privacy URL, terms URL, contact details, and pricing or paid-app settings where applicable.
Set up or request the global OAuth client for the public or integration app. Multiple-customer server-side Zendesk API access must use global OAuth tokens, not API tokens or regular OAuth tokens.
Implement OAuth state validation, token exchange, Secret Manager storage, runtime refresh, revocation posture, disconnect, uninstall, and authorization failure handling.
Implement Zendesk Marketplace request headers for external Zendesk API requests once Zendesk provides the Marketplace name, organization ID, and app ID or bot ID. Preserve a test-account verification path for Zendesk review.
Implement tenant/account mapping, setup-required behavior, governed ticket creation proposal, execution, idempotency, audit trail, and failure handling.
Add field allowlists for priority, tags, status, requester attribution, and custom fields before exposing them in public copy.
Prepare public setup/support, privacy, terms, security/data-handling, and data-deletion documentation.
Prepare Marketplace listing copy, sanitized screenshots, test instructions, reviewer account access, setup notes, expected ticket output, and cleanup instructions.
Complete Zendesk Marketplace automated checks and Zendesk review before making public-readiness claims.

If the v1 package uses a ZAF app to call Zendesk or Threada APIs from the browser, use ZAF client.request and secure settings/OAuth settings appropriately. Do not expose secrets in browser JavaScript. If using a server-side app flow, use signed URLs or JWT where required and validate all server-side callbacks and requests.

Explicit Non-Goals

No public Zendesk Marketplace claim until a first-class Zendesk app or integration app exists and Zendesk review passes.
No API token, regular OAuth token, private credential, or manually provisioned tenant secret as the public Marketplace install path.
No unmanaged direct Zendesk writes from the Marketplace app.
No broad ticket, user, organization, help center, sell, chat, messaging, admin, or customer-export scopes unless the exact v1 capability requires them and the implementation is validated end to end.
No autonomous AI ticketing-agent claim unless the product satisfies Zendesk’s requirements for standard ticketing channels, end-user and bot message history, end-user attribution, and dedicated bot-agent messaging.
No macro execution, bulk update, ticket merge, user/org mutation, or packaged Zendesk knowledge sync claim until an authenticated, tenant-scoped, auditable path exists and is reviewed.
No customer-data screenshots, raw ticket exports, requester lists, OAuth tokens, cookies, or private tenant payloads in Marketplace screenshots or review evidence.
No positioning as a generic “AI agent executes any Zendesk action” app. Public copy must stay anchored to governed ticket work, setup, and review.

Review Gates

Implemented:

Public API action types include zendesk_create_ticket and zendesk_update_ticket.
Public BFF mapping code converts Zendesk create-ticket and update-ticket payloads into governed action requests and proposal views.
Public API docs and generated OpenAPI are published.
Private Zendesk integration-app package scaffold exists at packages/zendesk-marketplace-app.
The scaffold generates a marketingOnly: true, private: false source package with manifest.json, translations/en.json, an asset checklist, Marketplace listing metadata, and readiness blockers.
Package validation rejects non-integration-app posture, missing data disclosure, invalid Marketplace URLs, malformed global OAuth identifiers, missing required assets, missing review behavior flags, missing explicit non-goals, and non-production URLs for submission readiness.
Public Zendesk setup/support documentation exists at Zendesk setup and support.
The package descriptor declares the public setup/support URL and Studio install handoff so docs crawl validation can prove the install contract is published before launch checks run.
Shared Marketplace OAuth install path supports Zendesk subdomain-scoped authorization, token exchange, Secret Manager credential storage, and enabled runtime integration upsert for governed zendesk_create_ticket execution.
Runtime Zendesk execution refreshes expired marketplace OAuth access tokens on use and writes refreshed tenant credentials as new Secret Manager versions.

Missing:

Zendesk Marketplace organization, developer profile, app listing, categories, real support/privacy/terms URLs in the Zendesk portal, and reviewer setup path.
Real logo.png, logo-small.png, three screenshots, and source ZIP packaged and validated with ZCLI and the Marketplace portal checks.
Zendesk-approved global OAuth client evidence, disconnect and revocation flows, and reviewer self-test evidence for multiple-customer server-side Zendesk API access.
Marketplace request-header implementation for external Zendesk API calls once Zendesk assigns the Marketplace identifiers.
Tenant/account mapping, setup-required, approval-pending, success, failure, idempotency, and audit behavior.
Ticket field allowlists and safe requester attribution.
Data disclosure, privacy/terms/security links, test instructions, setup notes, reviewer access, and cleanup instructions.
Zendesk Marketplace automated checks before submission, plus Zendesk review evidence and approval report before public-readiness claims.

Blocked:

Public Zendesk Marketplace submission is blocked until the first-class Zendesk app or integration app exists, runtime behavior is implemented and testable, global OAuth and request-header requirements are handled, automated checks pass, and reviewer setup is complete.
Public Zendesk Marketplace readiness and marketing claims are blocked until Zendesk review has accepted the submitted app or integration.

Launch Checklist

Keep the v1 Zendesk surface to the committed integration-app scaffold unless reviewer feedback requires an installable Support app.
Rebuild the package with real Threada support/privacy/terms URLs, support email, Zendesk Marketplace listing key, global OAuth identifier, sponsored test subdomain, and Marketplace organization/app identifiers.
Register the Marketplace organization/developer profile and create the Zendesk Marketplace submission draft.
Replace the scaffold asset checklist with real logo.png, logo-small.png, and three full-bleed screenshots, then run ZCLI validation/package, upload the source ZIP, and pass Zendesk’s automated checks.
Set up or request the global OAuth client, implement state validation, token exchange, Secret Manager storage, runtime refresh, revocation, disconnect, and authorization failure handling.
Implement Zendesk Marketplace request headers for external Zendesk API calls once Zendesk assigns the Marketplace identifiers.
Implement tenant/account mapping, setup-required behavior, governed create-ticket proposal creation, execution, idempotency, audit trail, and failure handling.
Add priority, tag, requester, status, and custom-field allowlists before exposing ticket update or comment behavior.
Create Marketplace listing copy, categories, pricing settings if required, sanitized screenshots, and demo or reviewer material for install, setup, proposal, approval, execution, resulting Zendesk ticket, and disconnect.
Prepare Zendesk reviewer account access, setup notes, expected ticket output, production URL evidence, and cleanup instructions through Zendesk-approved channels.
Complete Zendesk Marketplace automated checks.
Submit through Zendesk Marketplace review and resolve all review issues before claiming Zendesk Marketplace readiness.