Zendesk

Connector class

Zendesk sits between the two connector classes

TSANet connectors divide by one question: will the platform run your code inside the member's own tenant? Salesforce and Dynamics will, and ServiceNow would, though nothing is built there yet. Intercom will not, which is why that one is a hosted gateway. Zendesk is the interesting middle case — and understanding which half you are in explains most of the design below.

Architecture

Two layers, and one that no longer exists

Layer 1 is the ZAF app the agent sees. Layer 2 is ZIS, which holds the connections and receives inbound pushes. A third layer — a GitHub Actions workflow running a token-refresh job and an SLA monitor — has been retired: ZIS renews its own tokens now, and the ZAF background poller applies the SLA breach tag.

• 1Agent actions. The sidebar reads and writes the ticket through ZAF, and reaches TSANet only through client.request() — the ZAF proxy. Direct fetch() to an external host is CORS-blocked unless the domain is in manifest.json → domainWhitelist.
• 2Public reply forwarding. A Zendesk trigger fires on a public comment carrying tsanet_inbound or tsanet_outbound, posts to a Basic-auth webhook, and ZIS forwards it to the partner as a note. Internal comments never fire it, which is what keeps the note mirror loop-safe.
• 3ZAF → TSANet. Partner search, process form fetch, case submission and all lifecycle actions, proxied through Zendesk.
• 4Inbound push. TSANet posts to the ZIS generic inbound webhook using the callbackAuth credentials you registered. flow_handle_ping creates the Zendesk ticket.
• 5ZIS → TSANet. The action_ts_* actions call the Connect API through the tsanet_oauth connection, which mints and renews Entra tokens on its own.

Authentication

OAuth client credentials, and the scope that looks right but isn't

Server-to-server auth is an OAuth 2.0 client-credentials grant against Microsoft Entra. Unlike the legacy POST /v1/login JWT — which expires in about 60 minutes and has to be refreshed by something — the caller re-mints automatically from a long-lived client credential. That is what retired the token-refresh job on the ZIS side. The ZAF sidebar's own calls still cache a ~50-minute JWT (see the poller in the topology); which of the two schemes that token comes from has not been re-probed.

# Mint an Entra token
POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
  grant_type=client_credentials
  client_id={your TSANet-issued client id}
  client_secret={your TSANet-issued secret}
  scope={audience-guid}/.default      ← bare GUID
  scope=api://{audience-guid}/.default  ← AADSTS500011

• Use the bare audience GUID. The api:// prefix fails with AADSTS500011 — "resource principal not found" — because the Connect app registration publishes no Application ID URI. This looks like a typo and is not; every working scope is bare-GUID form.
• Service principal provisioning is required. The API accepts an app-only token only once TSANet has provisioned your service principal's object ID. That provisioning is also what maps your tokens to your member company. Send TSANet your service principal OID to be onboarded.
• No requestedAccessTokenVersion change is needed. The API accepts the default v1-format Entra token with a bare-GUID aud claim.
• Store secrets verbatim. Entra client secrets are random strings that can begin with punctuation — a leading . has been seen in production. "Cleaning" the value breaks authentication with AADSTS7000215. If the same secret works directly but fails through ZIS, the stored copy is corrupted: re-PATCH it and watch for paste artifacts.

Error responses have two modes, and the default is HTTP 500

This is permanent, documented behaviour rather than a bug to work around. With no Accept header — or application/json alone — most business-rule, validation and authorization rejections return HTTP 500 with a {"message": "..."} body, locked in for backward compatibility with existing clients.

# Recommended for every new integration
Accept: application/json, application/problem+json

That opts into RFC 7807: the same rejections return their documented status (400/401/403/404/409/422) with a {type, title, status, detail, instance} body. Branch on status code and read the message from detail, falling back to title. List application/json first — with application/problem+json alone, successful 200 responses also come back labelled Content-Type: application/problem+json, which confuses content-type-keyed consumers.

Lifecycle

Case states, and what the SLA actually measures

• Gate every SLA display and breach check on responded === false. Showing a countdown on an ACCEPTED case is showing a deadline TSANet is no longer tracking.
• Only the submitting company can close. Calling /closure as the receiver returns an error, so show the Close action only when direction === 'OUTBOUND'.
• token is the primary key — save it the moment a case is created. The numeric id exists but every API path uses token.
• PENDINGACTION is an additional status the /v2 list endpoints return and filter on; it surfaces cases awaiting an action from your side.
• Zendesk date fields are YYYY-MM-DD only. An ISO datetime like 2026-05-08T14:00:00Z is silently rejected — truncate respondBy with .substring(0, 10).

Note visibility

Three audiences, and a composer that only offers two

The governing rule is simple: only public content reaches the partner; internal notes stay in Zendesk. The complication is that a note has three possible audiences and Zendesk's native composer is binary — an app cannot add a third option to the built-in Public reply / Internal note toggle.

• The author guard fails closed. Forwarding happens only when the comment author's role is Agent or Admin; an end-user public reply never forwards. Note that {{current_user.role}} renders the literal Admin, not Administrator, and ZIS Choice supports only StringEquals — so list every accepted value explicitly, lowercase variants included.
• The mirror is loop-safe by construction. It writes internal comments, which never re-fire the public-comment trigger.
• Echo suppression: the mirror skips a note that is self-authored and matches an existing public comment, so a forwarded reply doesn't bounce back as a redundant internal copy. Partner notes are never suppressed, even on a text collision.
• Dedup on a marker, not on text. Every mirrored comment carries tsanet-note-id:<id> in the body. The native field-action path writes a receipt comment with the same marker, so there is exactly one internal record whether or not ZAF is installed.
• Notes come back as HTML. Strip summary and description to plain text before display. The process form's adminNote is the exception — see below.

The Add Note payload

summary is required and capped at 500 characters; description is optional and capped at 5,000. The TSANet web UI renders both as separate labelled sections, so posting identical values shows the text twice — it looks like a duplication bug and is intentional rendering. Present two fields, Subject and Details, and only include description if the agent filled it in. Never auto-copy one into the other.

ZAF constraints

What the sandbox takes away

ZAF apps run in cross-origin sandboxed iframes inside Zendesk. Three consequences drive most of the app's shape.

Setup

The path through installation

The ZIS integration name is globally unique across all of Zendesk

This is documented vendor behaviour, and it is the single most expensive thing on this page to learn at runtime. Register a name and no other Zendesk customer can ever use it. tsanet_connect is already claimed, so every member needs their own name — the app exposes it as the tsanet_integration_name setting (charset ^[a-z0-9_-]{1,64}$).

POST /api/services/zis/registry/{your_integration_name}
400 {"message":"the integration: tsanet_connect is not available for upsert by this account"}
# Not a permissions fault. Not retryable. Pick your own name.

• Use the OAuth client ZIS creates for you. The registry create returns a zendesk_oauth_client object with identifier zis_<integration-name>; its numeric id is what mints ZIS tokens. A hand-created client is refused on every ZIS management endpoint with 401 Authorization failed due to integration mismatch.
• Renaming does not retire the old integration. Its job specs stay installed and keep intercepting the same events, so both act on every inbound collaboration and tickets get created twice. Connections are integration-scoped too, so both have to be recreated under the new name.
• ZIS custom integrations are invisible in Admin Center. Verify over the API — this is by design, not a broken install.

Inbound push registration is two calls, and the version matters

# 1. On Zendesk — returns ingest URL + Basic credentials, shown once
POST /api/services/zis/inbound_webhooks/generic/{integration}

# 2. On TSANet — subscribe TSANet to that URL
POST /v1/webhooks
{ "callbackUrl": "<ingest URL>",
  "callbackAuth": { "type": "BASIC", "username": "...", "password": "..." } }

Omit eventTypes and the subscription covers what the bundle expects — collaboration-request.created and note.created. Those are the only two event types v1 delivers — the specification's own v1 tag says so — so omitting eventTypes cannot subscribe the bundle to more; the three v2-only types never reach a v1 subscription. Save the response id for later management and the secret (the HMAC key, returned only at creation).

callbackAuth arrived in Connect API v3.1.0 and was validated on Beta. Since app v1.0.69 the inbound case's own customFields are surfaced too, appended to the created ticket as a "Partner form fields" block; they arrive unordered, so the bundle sorts them by displayOrder.

Platform gotchas

Things that cost real debugging time

Zendesk side

# The pattern that works
GET  /api/v2/tickets/{id}.json
PUT  /api/v2/tickets/{id}.json
{ "ticket": { "tags": [...existing, "new_tag"] },
  "safe_update": true,
  "updated_stamp": "<ticket.updated_at>" }
# A stale stamp returns 409 UpdateConflict and writes nothing —
# a concurrent edit fails loudly instead of being clobbered.

• Verify a tag write from the ticket audit, never from the API response. Both failing calls above return success. Recovery for tags already lost: GET /api/v2/tickets/{id}/audits.json, find events with field_name: tags, and previous_value holds the replaced list.
• Trigger field names: use current_tags, not tags, for tag conditions, and assignee_id, not assignee, for recipients. Wrong values return "Invalid rule target" — or fail silently.
• The Views API silently ignores custom field columns in execution.columns. Add them by hand in Admin Center after creating the view.
• Internal comments go through the ticket endpoint: PUT /api/v2/tickets/{id}.json with ticket.comment.public: false. The Comments endpoint does not support the internal flag the same way.
• ZIS auth failures discriminate cleanly — read the exact string. 401 integration mismatch means the credential is valid but was minted from the wrong OAuth client, or the integration in the path is not registered. 401 Authentication failed means the bearer is missing, malformed or expired. 403 API token is not supported means an API token was sent where a ZIS OAuth token is required.
• Registry create is admin-only, and client-credentials tokens act as the user their OAuth client was created under — so create that client while signed in as an administrator.
• Hiding the app is an install-time role/group restriction, and it hides every surface at once: sidebar, nav entry and background poller. The allowed_action_roles setting is defence in depth for who can invoke actions, not a way to hide anything. Neither is a security boundary — the TSANet API credential is the real control.

TSANet side

• engineerEmail is required on approval, and its domain rule is undocumented. The specification marks the field required — omitting it still returns "Error processing request" with no useful detail — but nothing documents that the address must be from your company's TSANet-registered domain. An agent's own Zendesk email fails domain validation, so use the dedicated API user's address.
• SELECT field options are newline-delimited, not comma-delimited. The process form's customFields[].options separates choices with CRLF, and the structured selections[] array is frequently empty. Splitting on commas collapses every choice into one option. Parse selections[].value first, then split on newlines, then fall back to commas.
• adminNote is authored HTML to render, not strip. The form's "Partner instructions" field carries formatted text and links the partner wrote. Escaping shows raw tags; stripping loses the links. Sanitize against a tag allowlist and render, forcing links to target="_blank" rel="noopener noreferrer" with http(s):-only hrefs. This is the one field that is the exception to stripping HTML.
• documentId is required on submission and must be fetched fresh from the form endpoint every time. Vendors update their forms; do not cache it long-term.
• Partner search returns an array. A company with multiple departments returns multiple results — use departmentId for precise routing when it is available.
• There is no /v1/cases endpoint. It is a common wrong guess that returns 404. The list endpoints are /v2/collaboration-requests (paginated, returns {content:[...]}) and /v2/collaboration-requests/list (plain array, supports updatedAfter).
• testSubmission: true submits without creating real SLA timers or partner notifications.

Deprecation clocks

Dates worth putting in your calendar

Two independent retirement schedules affect this connector. Neither is a TSANet decision, and both have hard dates.

• The zendesk connection is now OAuth, not basic auth. It runs a client-credentials grant against the member's own instance, with token_url pointed at https://{subdomain}.zendesk.com/oauth/tokens. Tokens from clients created on or after 2026-04-30 expire in 30 minutes, so a static bearer connection is not viable — only the auto-renewing OAuth type works.
• The backing client must be kind: "confidential" at creation. The grant rejects public clients with unauthorized_client, and changing kind afterwards regenerates the secret while only ever displaying it truncated.
• Minimal scope is read tickets:write. tickets:read alone breaks search — /api/v2/search.json returns 403 under it, and there is no search:read scope.
• Migrating an existing install: connection names are unique across types, so delete the old basic_auth connection named zendesk and create the OAuth one under the same name. Zero bundle changes.

Build with an assistant

The implementation skill, and how to load it

The connector repository ships an agent skill — SKILL_TSANet_Connect.md — distilled from the production implementation: the two-layer architecture, the OAuth setup and its traps, the custom-field scheme, the lifecycle rules, and the platform gotchas on this page in a form an agentic coding assistant can apply while it works in your codebase. It is a plain markdown file with skill frontmatter (name, description and a trigger key), so it loads into Claude Code and any other assistant that accepts an instruction file. It is not quite self-contained: its PII-retention section points at a sibling file, PII_Retention_and_Data_Handling.md, in the same repository, so fetch that alongside it. Every skill TSANet ships, and how to load one into any assistant, is collected on Agentic usage with TSANet Connect.

Loading it

Claude Code — put it in your integration project's skills directory; from then on it triggers automatically whenever the work touches TSANet, ZAF or ZIS:

mkdir -p .claude/skills/tsanet-connect
curl -o .claude/skills/tsanet-connect/SKILL.md \
  https://raw.githubusercontent.com/tsanetgit/Zendesk_App/main/SKILL_TSANet_Connect.md

Other assistants — add the same file to whatever your tool treats as project instructions (a rules file, a context attachment). Nothing in it is Claude-specific. The skill lives in the connector repository and evolves with it, so re-download it when you upgrade the connector.

Typical first steps

• Start with routing, not code. "We're installing TSANet Connect for Zendesk — which layer do we need, and what should we provision first?" The skill's first job is deciding between the ZAF app, ZIS, and a custom REST path, and it will surface prerequisites before you hit them.
• Do auth with it, not after it. "Walk me through the ZIS OAuth client-credentials setup." The scope format that looks right and fails, and the secret-handling rules, are exactly the traps it exists to catch — the same ones under Authentication above.
• Paste errors verbatim. An AADSTS code or a silent no-op delivery means more to the skill than a paraphrase — several of this platform's failures look unrelated to their cause.
• Have it review before you install. "Review my custom-field scheme and trigger conditions against the skill's field reference" is cheaper than re-provisioning a live tenant.