feat(zoho-desk): add Self Client service-account credential

Adds a second way to connect Zoho Desk, alongside the interactive OAuth flow: a
Zoho Self Client, pasted as client id + client secret + organization id. Built
on the existing client-credential-accounts framework rather than a new credential
path, so it behaves like the Zoom Server-to-Server and Box CCG accounts already
in the repo - a short-lived token minted on demand, no refresh token.

Two Zoho behaviors the generic framework does not cover:
- `scope` must be COMMA-separated on Zoho's token endpoint; a space-separated
  list is rejected as an invalid scope. The list comes from
  getCanonicalScopesForProvider('zoho-desk'), so the Self Client and the OAuth
  flow can never drift apart on scopes.
- Zoho reports OAuth failures in the JSON body, frequently with HTTP 200
  (e.g. {"error":"invalid_client"}), so the success body is inspected for an
  `error` field before the token is read - a status-only check would accept a
  failed mint.

deriveZohoDeskBaseFromApiDomain moves out of auth.ts into the dependency-free
host-allowlist module so the minter and the OAuth path share one derivation
instead of duplicating it, and the mint response's api_domain now flows through
to tools as `apiDomain` (the SA branch of the token route previously returned
none, so SA calls would have assumed desk.zoho.com).

Docs: hand-authored zoho-desk-service-account.mdx following the existing
*-service-account.mdx pages, registered in meta.json and in the generator's
keep-list so stale-page cleanup does not delete it.

Known limitation, documented in the descriptor helpText and the docs page:
webhook triggers still require an OAuth connection. Webhook provisioning resolves
credentials through getCredentialOwner/refreshAccessTokenIfNeeded, which is
OAuth-account-only for every provider in the repo - not a Zoho-specific gap.

Unverified from documentation, needs a live Zoho org before merge:
- the `ZohoDesk.` soid prefix. Zoho documents only the syntax
  {servicename}.{zsoid} with a single CRM example; no first-party doc states the
  Desk prefix. normalizeZohoDeskSoid passes through any value already containing
  a '.', so an operator can paste a corrected full soid without a code change.
- whether zsoid is the same identifier as the Desk orgId header value.
- whether the client-credentials endpoint accepts Desk.webhooks.CREATE/DELETE
  for a Self Client.
- whether the mint response populates api_domain for Desk (documented for CRM);
  if absent the derivation falls back to the US Desk host.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/meta.json

@@ -261,6 +261,7 @@
     "zendesk",
     "zep",
     "zerobounce",
+    "zoho-desk-service-account",
     "zoho_desk",
     "zoom",
     "zoom-service-account",

apps/docs/content/docs/en/integrations/zoho-desk-service-account.mdx

@@ -0,0 +1,141 @@
+---
+title: Zoho Desk Self Clients
+description: Set up a Zoho Self Client so your workflows can call Zoho Desk without a personal OAuth login
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+import { FAQ } from '@/components/ui/faq'
+
+A Zoho **Self Client** is an OAuth client that has no redirect URL and no end user. Instead of sending someone through a consent screen, your workflows authenticate to Zoho Desk with the client's own ID and secret, and Sim mints a short-lived access token on demand — no user consent to expire, and no personal login that breaks when someone leaves the team.
+
+This is the recommended way to use Zoho Desk in production workflows: the credential belongs to your organization rather than a person, the granted scopes are explicit, and tokens are minted fresh whenever a workflow runs.
+
+## Prerequisites
+
+You need a Zoho account with access to the [Zoho API Console](https://api-console.zoho.com) for the same organization your Zoho Desk portal belongs to, and the Zoho Desk **organization ID** for that portal.
+
+<Callout type="warn">
+Sim's Zoho Desk integration authenticates against the US accounts server (`accounts.zoho.com`). Organizations hosted in another Zoho data center (EU, IN, AU, JP, CA, SA, CN, UK) cannot mint tokens through this flow. Once a token is minted, API calls are routed to the Desk host for the data center Zoho reports, so data residency is honored for the calls themselves.
+</Callout>
+
+<Callout type="warn">
+Zoho Desk **webhooks are a Professional-edition and above feature**. The Zoho Desk trigger in Sim provisions a webhook subscription, so it does not work on Free or Standard plans. The trigger also requires a personal **OAuth** connection rather than a Self Client — see [Triggers](#triggers-still-need-oauth) below.
+</Callout>
+
+## Setting Up the Self Client
+
+### 1. Create the Self Client
+
+<Steps>
+  <Step>
+    Sign in at [api-console.zoho.com](https://api-console.zoho.com) with the Zoho account that owns the Desk portal
+  </Step>
+  <Step>
+    Click **Add Client**, choose **Self Client**, and click **Create** — then **OK** on the confirmation
+
+    {/* TODO(screenshot): Zoho API Console Add Client dialog with Self Client selected */}
+  </Step>
+  <Step>
+    Open the new client and switch to the **Client Secret** tab. Copy the **Client ID** and **Client Secret** — these are two of the three values you'll paste into Sim
+
+    {/* TODO(screenshot): Self Client Client Secret tab showing Client ID and Client Secret */}
+  </Step>
+</Steps>
+
+<Callout type="info">
+You do **not** need the **Generate Code** tab. That tab produces a one-time authorization code for the code-exchange flow; the client-credentials flow Sim uses needs only the client ID, the client secret, and your organization ID.
+</Callout>
+
+### 2. Find Your Organization ID
+
+<Steps>
+  <Step>
+    Open Zoho Desk and go to **Setup** (the gear icon) → **Developer Space** → **API**
+  </Step>
+  <Step>
+    Copy the numeric **Organization ID** (also called the Org ID or portal ID) shown there — for example `600123456`
+
+    {/* TODO(screenshot): Zoho Desk Setup > Developer Space > API showing the Organization ID */}
+  </Step>
+</Steps>
+
+<Callout type="warn">
+This must be the organization ID of the Desk portal you want the workflows to act on. If your Zoho account has more than one Desk portal, using the wrong ID makes Zoho either reject the token request or issue a token scoped to the wrong portal.
+</Callout>
+
+### 3. Scopes
+
+Sim requests exactly the scopes its Zoho Desk tools and trigger exercise:
+
+```
+Desk.tickets.READ
+Desk.tickets.UPDATE
+Desk.contacts.READ
+Desk.basic.READ
+Desk.webhooks.CREATE
+Desk.webhooks.DELETE
+aaaserver.profile.READ
+```
+
+Sim sends this list on every token request, so there is nothing to pre-configure on the Self Client itself. If Zoho rejects the request with an invalid-scope error, the Self Client's owner does not have access to one of the Desk modules above in that organization.
+
+A scope that is granted but insufficient surfaces at run time as a `4xx` from the Zoho Desk API naming the scope problem.
+
+### 4. Protect the Client Secret
+
+The client secret is bearer material for your Zoho Desk organization, limited only by the scopes above. Treat it like a password — do not commit it to source control or share it publicly. Sim encrypts it at rest.
+
+<Callout type="info">
+Regenerating or revoking the Self Client in the Zoho API Console invalidates the stored pair immediately. If you rotate it, update the credential in Sim right away.
+</Callout>
+
+## Adding the Self Client to Sim
+
+<Steps>
+  <Step>
+    Open **Integrations** from your workspace sidebar
+  </Step>
+  <Step>
+    Search for "Zoho Desk" and open it, then click **Add to Sim** and choose **Add Self Client**
+
+    {/* TODO(screenshot): Zoho Desk integration page with the Add Self Client connect option */}
+  </Step>
+  <Step>
+    In the **Add Zoho Desk Self Client** dialog, paste the **Client ID**, the **Client secret**, and the numeric **Organization ID**, and optionally set a display name and description
+
+    {/* TODO(screenshot): Add Zoho Desk Self Client dialog with all three fields filled in */}
+  </Step>
+  <Step>
+    Click **Add Self Client**. Sim verifies the credentials by minting a real access token from Zoho — if it fails, the error tells you whether Zoho rejected the credentials or couldn't be reached.
+  </Step>
+</Steps>
+
+## Using the Self Client in Workflows
+
+Add a Zoho Desk block to your workflow. In the credential dropdown, your Self Client appears alongside any OAuth credentials. Select it and configure the block as you normally would.
+
+{/* TODO(screenshot): Zoho Desk block in a workflow with the Self Client selected as the credential */}
+
+The block calls the Zoho Desk REST API with a freshly minted access token — the same requests as the OAuth flow, so every Zoho Desk tool works, subject to the scopes above.
+
+### Triggers still need OAuth
+
+The Zoho Desk **trigger** provisions and tears down its own webhook subscription against your Desk organization, and that provisioning path currently runs only against a personal OAuth connection. Connect a Zoho Desk account through OAuth for triggers, and use the Self Client for the blocks that read and update tickets.
+
+## Token Behavior
+
+Access tokens minted from a Self Client live for one hour and there is **no refresh token** — Sim mints a new token whenever one is needed, and caches the current one until it is close to expiry. Two events invalidate the stored credential:
+
+- **Revoking or deleting the Self Client** in the Zoho API Console — no new tokens can be minted
+- **Regenerating the client secret** — the stored pair stops working; paste the new secret into the credential in Sim
+
+<FAQ items={[
+  { question: "Why a Self Client instead of OAuth?", answer: "A Self Client authenticates as your Zoho organization, not as a person — nothing expires when someone leaves or their login lapses. Sim mints short-lived tokens from the stored client ID and secret whenever a workflow runs." },
+  { question: "Where do I find the Organization ID?", answer: "In Zoho Desk, go to Setup (gear icon) → Developer Space → API. The numeric Organization ID shown there is the value to paste. It is the same ID that Zoho Desk API calls send in the orgId header." },
+  { question: "Zoho rejects my credentials with invalid_client — why?", answer: "Either the client ID or secret was mistyped, or the client you created is not a Self Client. Only Self Clients support the client-credentials grant — in the Zoho API Console, Add Client → Self Client. Copy both values from the client's Client Secret tab." },
+  { question: "Zoho returns missing_org_info or rejects the organization — why?", answer: "Zoho could not resolve a Desk organization from the ID you pasted. Re-copy the numeric Organization ID from Setup → Developer Space → API in the Desk portal you want to use. If your Zoho account has multiple Desk portals, make sure it is the ID of the right one." },
+  { question: "Can I use a Self Client with a non-US Zoho account?", answer: "Not currently. Sim's Zoho Desk integration authenticates against the US accounts server, accounts.zoho.com. An organization in another Zoho data center must authenticate against its own accounts server, which this flow does not support." },
+  { question: "Why doesn't my Zoho Desk trigger work with the Self Client?", answer: "The trigger provisions a webhook subscription in your Desk organization, and that path runs against a personal OAuth connection only. Connect Zoho Desk through OAuth for triggers. Separately, Zoho Desk webhooks require a Professional-edition plan or above — they are unavailable on Free and Standard." },
+  { question: "How do I rotate the credentials?", answer: "Regenerate the client secret on the Self Client's Client Secret tab in the Zoho API Console, then update the credential in Sim with the new secret. The old secret stops working as soon as it's regenerated, so update Sim promptly." },
+]} />

apps/sim/app/api/auth/oauth/token/route.ts

@@ -186,6 +186,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
             cloudId: result.cloudId,
             domain: result.domain,
             instanceUrl: result.instanceUrl,
+            apiDomain: result.apiDomain,
             authStyle: result.authStyle,
           },
           { status: 200 }

apps/sim/app/api/auth/oauth/utils.ts

@@ -354,6 +354,11 @@ export interface ServiceAccountTokenResult {
   domain?: string
   /** Salesforce only — the org's instance URL the token must be used against. */
   instanceUrl?: string
+  /**
+   * Zoho Desk only — the data-center-scoped Desk REST base the token must be
+   * used against, forwarded to tools as their `apiDomain` param.
+   */
+  apiDomain?: string
   /**
    * Set when the token must be sent in an `x-api-token` header instead of
    * `Authorization: Bearer` (e.g. Pipedrive personal API tokens). Absent means
@@ -397,6 +402,8 @@ interface CachedClientCredentialToken {
   secretFingerprint: string
   /** Salesforce only — the instance URL returned alongside the minted token. */
   instanceUrl?: string
+  /** Zoho Desk only — the Desk REST base derived from the token's api_domain. */
+  apiDomain?: string
 }
 
 interface FailedClientCredentialMint {
@@ -488,7 +495,11 @@ async function resolveClientCredentialAccountToken(
       cached.secretFingerprint === secretFingerprint &&
       cached.expiresAtMs - Date.now() > CLIENT_CREDENTIAL_TOKEN_MIN_TTL_MS
     ) {
-      return { accessToken: cached.accessToken, instanceUrl: cached.instanceUrl }
+      return {
+        accessToken: cached.accessToken,
+        instanceUrl: cached.instanceUrl,
+        apiDomain: cached.apiDomain,
+      }
     }
 
     const failed = clientCredentialMintFailureCache.get(credentialId)
@@ -522,8 +533,13 @@ async function resolveClientCredentialAccountToken(
         expiresAtMs: Date.now() + mint.expiresInSeconds * 1000,
         secretFingerprint,
         instanceUrl: mint.instanceUrl,
+        apiDomain: mint.apiDomain,
       })
-      return { accessToken: mint.accessToken, instanceUrl: mint.instanceUrl }
+      return {
+        accessToken: mint.accessToken,
+        instanceUrl: mint.instanceUrl,
+        apiDomain: mint.apiDomain,
+      }
     } catch (error) {
       clientCredentialMintFailureCache.set(credentialId, {
         error,

apps/sim/lib/api/contracts/oauth-connections.ts

@@ -86,6 +86,8 @@ const oauthTokenResponseSchema = z.object({
   accessToken: z.string(),
   idToken: z.string().optional(),
   instanceUrl: z.string().optional(),
+  /** Zoho Desk — the data-center-scoped Desk REST base for this credential. */
+  apiDomain: z.string().optional(),
   cloudId: z.string().optional(),
   domain: z.string().optional(),
   authStyle: z.enum(['x-api-token']).optional(),

apps/sim/lib/auth/auth.ts

@@ -109,7 +109,7 @@ import { joinInstanceOrganization } from '@/lib/organizations/instance-org'
 import { captureServerEvent, getPostHogClient } from '@/lib/posthog/server'
 import { disableUserResources } from '@/lib/workflows/lifecycle'
 import { SSO_TRUSTED_PROVIDERS } from '@/ee/sso/constants'
-import { isZohoHost } from '@/tools/zoho_desk/host-allowlist'
+import { deriveZohoDeskBaseFromApiDomain } from '@/tools/zoho_desk/host-allowlist'
 
 const logger = createLogger('Auth')
 
@@ -160,31 +160,6 @@ function getMicrosoftUserInfoFromIdToken(tokens: { accessToken?: string }, provi
   }
 }
 
-/**
- * Derive the Zoho Desk REST base URL from the token response `api_domain`
- * (e.g. `https://www.zohoapis.eu` -> `https://desk.zoho.eu`). Zoho returns the
- * data-center-scoped `api_domain` on the `www.zohoapis.*` host, but the Desk
- * REST API lives on `desk.zoho.*` in the same data center. Persisting the
- * derived Desk base (instead of assuming `desk.zoho.com`) honors data residency.
- */
-function deriveZohoDeskBaseFromApiDomain(apiDomain?: string): string {
-  const fallback = 'https://desk.zoho.com'
-  if (!apiDomain) return fallback
-  try {
-    const host = new URL(apiDomain).host.toLowerCase()
-    // Gate on the strict Zoho apex allowlist before trusting the host: a loose
-    // `desk.zoho.*` pattern would accept a lookalike like `desk.zoho.com.attacker.com`
-    // and persist it as the credential's REST base, later leaking the OAuth token.
-    if (!isZohoHost(host)) return fallback
-    // Map the data-center TLD from the (now trusted) host onto the Desk REST host
-    // in the same data center - works for both www.zohoapis.<tld> and desk.zoho.<tld>.
-    const match = host.match(/zoho(?:apis)?\.([a-z.]+)$/)
-    return match?.[1] ? `https://desk.zoho.${match[1]}` : fallback
-  } catch {
-    return fallback
-  }
-}
-
 const additionalTrustedOrigins = parseOriginList(env.TRUSTED_ORIGINS, (value) =>
   logger.warn('Ignoring invalid entry in TRUSTED_ORIGINS', { value })
 )

apps/sim/lib/credentials/client-credential-accounts/descriptors.ts

@@ -54,11 +54,13 @@ export interface ClientCredentialAccountDescriptor {
 export const ZOOM_SERVICE_ACCOUNT_PROVIDER_ID = 'zoom-service-account' as const
 export const BOX_SERVICE_ACCOUNT_PROVIDER_ID = 'box-service-account' as const
 export const SALESFORCE_SERVICE_ACCOUNT_PROVIDER_ID = 'salesforce-service-account' as const
+export const ZOHO_DESK_SERVICE_ACCOUNT_PROVIDER_ID = 'zoho-desk-service-account' as const
 
 export type ClientCredentialAccountProviderId =
   | typeof ZOOM_SERVICE_ACCOUNT_PROVIDER_ID
   | typeof BOX_SERVICE_ACCOUNT_PROVIDER_ID
   | typeof SALESFORCE_SERVICE_ACCOUNT_PROVIDER_ID
+  | typeof ZOHO_DESK_SERVICE_ACCOUNT_PROVIDER_ID
 
 /**
  * Allowed My Domain host shapes: one org label (optionally with a
@@ -85,6 +87,35 @@ export function normalizeSalesforceMyDomainHost(rawHost: string): string {
     .toLowerCase()
 }
 
+/**
+ * Zoho's `soid` token parameter is documented only as the syntax
+ * `{servicename}.{zsoid}` with a single Zoho CRM example
+ * (`ZohoCRM.600*****434`). Two things are NOT confirmed by Zoho's own docs:
+ *
+ * 1. that the Desk service name is literally `ZohoDesk` (inferred from the
+ *    documented syntax and corroborated only by community posts), and
+ * 2. that `zsoid` is the same value as the Desk `orgId` sent in the `orgId`
+ *    request header, rather than a distinct Zoho ServiceOrg id.
+ *
+ * Both need live verification against a real Zoho Desk org before this flow is
+ * relied on. The normalization is therefore deliberately permissive: a value
+ * that already carries a `{servicename}.` prefix (any dot) is passed through
+ * untouched, so an operator who learns the correct prefix or id can paste the
+ * full `soid` and bypass the inference entirely. A bare id is prefixed with
+ * `ZohoDesk.`.
+ *
+ * Shared by the connect modal's format hint and the server-side minter so both
+ * judge the same normalized value.
+ */
+export function normalizeZohoDeskSoid(rawOrgId: string): string {
+  const trimmed = rawOrgId.trim()
+  if (!trimmed || trimmed.includes('.')) return trimmed
+  return `ZohoDesk.${trimmed}`
+}
+
+/** A normalized `soid`: a service-name prefix plus a numeric Zoho org id. */
+export const ZOHO_DESK_SOID_REGEX = /^[A-Za-z]+\.\d+$/
+
 export const CLIENT_CREDENTIAL_ACCOUNT_DESCRIPTORS: Record<
   ClientCredentialAccountProviderId,
   ClientCredentialAccountDescriptor
@@ -179,6 +210,38 @@ export const CLIENT_CREDENTIAL_ACCOUNT_DESCRIPTORS: Record<
     helpText:
       'The Connected App must have "Enable Client Credentials Flow" checked with a "Run As" integration user set under Edit Policies — every call executes with that user\'s permissions, and deactivating or freezing the user stops all runs.',
   },
+  [ZOHO_DESK_SERVICE_ACCOUNT_PROVIDER_ID]: {
+    providerId: ZOHO_DESK_SERVICE_ACCOUNT_PROVIDER_ID,
+    serviceLabel: 'Zoho Desk',
+    connectNoun: 'Self Client',
+    fields: [
+      {
+        id: 'clientId',
+        label: 'Client ID',
+        placeholder: "Client ID from the Self Client's Client Secret tab",
+        secret: false,
+      },
+      {
+        id: 'clientSecret',
+        label: 'Client secret',
+        placeholder: 'Paste the client secret',
+        secret: true,
+      },
+      {
+        id: 'orgId',
+        label: 'Organization ID',
+        placeholder: '600123456',
+        secret: false,
+        hintPattern: ZOHO_DESK_SOID_REGEX,
+        hintNormalize: normalizeZohoDeskSoid,
+        hintMessage:
+          'Paste the numeric Zoho Desk organization ID from Setup → Developer Space → API, or the full ZohoDesk.<orgId> value.',
+      },
+    ],
+    docsUrl: 'https://docs.sim.ai/integrations/zoho-desk-service-account',
+    helpText:
+      'Create the Self Client in the Zoho API Console, add the Zoho Desk scopes, and use the organization ID from Setup → Developer Space → API. Only Zoho accounts in the US data center (accounts.zoho.com) are supported, and Zoho Desk triggers still require an OAuth connection.',
+  },
 }
 
 /**