feat(zoho-desk): let the service account pick its data center

Zoho's accounts server is per region, and the integration pinned every call to
the US host. For the interactive OAuth flow that is currently unavoidable -
better-auth's authorize/token URLs are static per provider - but the service
account mints its own token, so the region can simply be chosen. This makes the
Self Client the only way a non-US Zoho org can connect.

Adds an optional `dataCenter` field to the client-credential framework. Optional
matters: ClientCredentialAccountFieldId and ClientCredentialAccountFields are
shared with Zoom, Box and Salesforce, whose descriptors and minters are
unchanged. Blank keeps the previous behavior (US), so existing credentials are
unaffected.

Only us/eu/in/au are offered - the four regions where both the accounts server
and the Desk REST host are confirmed. CA is deliberately absent: Zoho's accounts
docs say accounts.zohocloud.ca while Zoho's own Desk SDK says accounts.zoho.ca,
and the two cannot both be right. JP/SA/CN/UK lack a confirmed Desk host.

The Desk base is now derived from the selected region rather than inferred from
the mint response, which also removes a dependency on `api_domain` being
populated for Desk (Zoho documents it for CRM only). When `api_domain` IS present
and disagrees with the region, it wins - it is authoritative about where the
token actually works - and the mismatch is logged so a mis-selected region is
diagnosable. deriveZohoDeskBaseFromApiDomain gains a `try` variant returning
undefined so an untrusted api_domain can no longer masquerade as an authoritative
US answer and silently override a correct region.

A wrong region fails loudly rather than silently: the minter runs as verification
on both create and reconnect, so the credential is never persisted in a broken
state. Because Zoho reports it as `invalid_client` - a Self Client only exists on
its own region's accounts server - the operator hint for that code now names the
data center as a candidate cause.

Copy is scoped per path rather than blanket "US only": the OAuth service
description, trigger setup instructions, and the docs intro now say which path
each limitation applies to, and the service-account page documents the four
regions with a sign-in-domain to region-code table.

Author: waleedlatif1

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

@@ -15,8 +15,10 @@ This is the recommended way to use Zoho Desk in production workflows: the creden
 
 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 type="info">
+A Self Client can authenticate against the **US, EU, IN, or AU** accounts server — pick your region with the **Data center** field when you add the credential, or leave it blank for US. Organizations in the JP, CA, SA, CN, or UK data centers are not supported yet. API calls are then routed to the Desk host for that same region, so data residency is honored end to end.
+
+The interactive **OAuth** connection is a separate path and remains **US-only** (`accounts.zoho.com`), so a non-US organization can connect only through a Self Client.
 </Callout>
 
 <Callout type="warn">
@@ -64,7 +66,20 @@ You do **not** need the **Generate Code** tab. That tab produces a one-time auth
 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
+### 3. Know Your Data Center
+
+Zoho hosts each organization in one data center, and the accounts server that issues tokens is per region. Look at the URL you use to sign in to Zoho Desk and pick the matching code:
+
+| Data center | Sign-in domain | Code to enter |
+| --- | --- | --- |
+| United States | `zoho.com` | `us` (or leave blank) |
+| Europe | `zoho.eu` | `eu` |
+| India | `zoho.in` | `in` |
+| Australia | `zoho.com.au` | `au` |
+
+Organizations in the JP, CA, SA, CN, and UK data centers cannot be connected yet.
+
+### 4. Scopes
 
 Sim requests exactly the scopes its Zoho Desk tools and trigger exercise:
 
@@ -82,7 +97,7 @@ Sim sends this list on every token request, so there is nothing to pre-configure
 
 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
+### 5. 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.
 
@@ -102,9 +117,9 @@ Regenerating or revoking the Self Client in the Zoho API Console invalidates the
     {/* 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
+    In the **Add Zoho Desk Self Client** dialog, paste the **Client ID**, the **Client secret**, and the numeric **Organization ID**. Set **Data center** to your region (`us`, `eu`, `in`, or `au`) — leave it blank for US. Optionally set a display name and description
 
-    {/* TODO(screenshot): Add Zoho Desk Self Client dialog with all three fields filled in */}
+    {/* TODO(screenshot): Add Zoho Desk Self Client dialog with all 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.
@@ -123,6 +138,8 @@ The block calls the Zoho Desk REST API with a freshly minted access token — th
 
 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.
 
+Because the OAuth flow is US-only, an organization outside the US data center can use Zoho Desk blocks through a Self Client but cannot use the Zoho Desk trigger.
+
 ## 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:
@@ -135,7 +152,8 @@ Access tokens minted from a Self Client live for one hour and there is **no refr
   { 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: "Can I use a Self Client with a non-US Zoho account?", answer: "Yes, for the US, EU, IN, and AU data centers. Set the Data center field to us, eu, in, or au when you add the credential, and Sim mints tokens against that region's accounts server and calls the Desk host in the same region. Leaving it blank means US. The JP, CA, SA, CN, and UK data centers are not supported yet, and the interactive OAuth connection remains US-only." },
+  { question: "I picked the wrong data center — what happens?", answer: "The region's accounts server does not know your organization, so Zoho rejects the token request and Sim reports that it could not authenticate. Edit the credential and set the Data center to the region whose domain you sign in to Zoho Desk with." },
   { 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/docs/content/docs/en/integrations/zoho_desk.mdx

@@ -31,7 +31,7 @@ To trigger on Zoho Desk activity instead, use the block's trigger mode. Sim crea
 
 > Zoho Desk webhooks require a Zoho Desk edition of **Professional or higher** — Free and Standard plans cannot create webhook subscriptions, so the trigger will fail to deploy on those plans.
 >
-> Sim currently supports Zoho accounts hosted in the **US data center** (`accounts.zoho.com`). Accounts in the EU, India, Australia, or Japan data centers cannot be connected yet.
+> Connecting a Zoho account with **OAuth** — which the trigger requires — works only for the **US data center** (`accounts.zoho.com`). To use Zoho Desk blocks from the EU, India, or Australia data centers, connect a [Self Client](/integrations/zoho-desk-service-account) instead and set its data center. The Japan, Canada, Saudi Arabia, China, and UK data centers are not supported by either path.
 {/* MANUAL-CONTENT-END */}
 
 

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

@@ -525,6 +525,7 @@ async function resolveClientCredentialAccountToken(
           clientId: blob.clientId,
           clientSecret: blob.clientSecret,
           orgId: blob.orgId,
+          dataCenter: blob.dataCenter,
         },
         { skipIdentity: true }
       )

apps/sim/app/api/credentials/[id]/route.ts

@@ -89,6 +89,7 @@ export const PUT = withRouteHandler(
         clientId: body.clientId,
         clientSecret: body.clientSecret,
         orgId: body.orgId,
+        dataCenter: body.dataCenter,
         request,
       })
       if (!result.success) {

apps/sim/app/api/credentials/route.ts

@@ -318,6 +318,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       clientId,
       clientSecret,
       orgId,
+      dataCenter,
     } = parsed.data.body
 
     const workspaceAccess = await checkWorkspaceAccess(workspaceId, session.user.id)
@@ -378,6 +379,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
           clientId,
           clientSecret,
           orgId,
+          dataCenter,
         })
         resolvedProviderId = secret.providerId
         resolvedAccountId = null

apps/sim/app/workspace/[workspaceId]/integrations/components/connect-service-account-modal/client-credential-account-modal.tsx

@@ -35,7 +35,10 @@ function messageForClientCredentialError(
   descriptor: ClientCredentialAccountDescriptor
 ): string {
   if (isApiClientError(err) && err.code) {
-    const fieldLabels = descriptor.fields.map((field) => field.label).join(', ')
+    const fieldLabels = descriptor.fields
+      .filter((field) => !field.optional)
+      .map((field) => field.label)
+      .join(', ')
     switch (err.code) {
       case 'invalid_credentials':
         return `We couldn't authenticate with those credentials. Check that the ${fieldLabels} all belong to the same ${descriptor.serviceLabel} app and that the app is authorized.`
@@ -92,6 +95,7 @@ export function ClientCredentialAccountModal({
   const [clientId, setClientId] = useState('')
   const [clientSecret, setClientSecret] = useState('')
   const [orgId, setOrgId] = useState('')
+  const [dataCenter, setDataCenter] = useState('')
   const [displayName, setDisplayName] = useState(initialDisplayName ?? '')
   const [description, setDescription] = useState(initialDescription ?? '')
   const [error, setError] = useState<string | null>(null)
@@ -104,6 +108,7 @@ export function ClientCredentialAccountModal({
     setClientId('')
     setClientSecret('')
     setOrgId('')
+    setDataCenter('')
     setDisplayName(initialDisplayName ?? '')
     setDescription(initialDescription ?? '')
     setError(null)
@@ -112,10 +117,12 @@ export function ClientCredentialAccountModal({
   const clientIdField = descriptor.fields.find((field) => field.id === 'clientId')
   const clientSecretField = descriptor.fields.find((field) => field.id === 'clientSecret')
   const orgIdField = descriptor.fields.find((field) => field.id === 'orgId')
+  const dataCenterField = descriptor.fields.find((field) => field.id === 'dataCenter')
 
   const trimmedClientId = clientId.trim()
   const trimmedClientSecret = clientSecret.trim()
   const trimmedOrgId = orgId.trim()
+  const trimmedDataCenter = dataCenter.trim()
   const isPending = createCredential.isPending || updateCredential.isPending
   const isDisabled = !trimmedClientId || !trimmedClientSecret || !trimmedOrgId || isPending
 
@@ -136,6 +143,7 @@ export function ClientCredentialAccountModal({
         clientId: trimmedClientId,
         clientSecret: trimmedClientSecret,
         orgId: trimmedOrgId,
+        dataCenter: trimmedDataCenter || undefined,
       }
       if (credentialId) {
         await updateCredential.mutateAsync({
@@ -227,6 +235,21 @@ export function ClientCredentialAccountModal({
           />
         )}
 
+        {dataCenterField && (
+          <ChipModalField
+            type='input'
+            title={dataCenterField.label}
+            value={dataCenter}
+            onChange={(value) => {
+              setDataCenter(value)
+              if (error) setError(null)
+            }}
+            placeholder={dataCenterField.placeholder}
+            autoComplete='off'
+            hint={hintFor(dataCenterField, trimmedDataCenter) ?? dataCenterField.hintMessage}
+          />
+        )}
+
         <ChipModalField
           type='input'
           title='Display name'

apps/sim/hooks/queries/credentials.ts

@@ -147,6 +147,7 @@ export function useUpdateWorkspaceCredential() {
           clientId: payload.clientId,
           clientSecret: payload.clientSecret,
           orgId: payload.orgId,
+          dataCenter: payload.dataCenter,
         },
       })
     },

apps/sim/lib/api/contracts/credentials.ts

@@ -133,6 +133,8 @@ export const createCredentialBodySchema = z
     clientId: z.string().trim().min(1).max(512).optional(),
     clientSecret: z.string().trim().min(1).max(1024).optional(),
     orgId: z.string().trim().min(1).max(255).optional(),
+    /** Optional provider region selector (Zoho Desk data center). */
+    dataCenter: z.string().trim().min(1).max(32).optional(),
   })
   .superRefine((data, ctx) => {
     if (data.type === 'oauth') {
@@ -207,6 +209,7 @@ export const updateCredentialByIdBodySchema = z
     clientId: z.string().trim().min(1).max(512).optional(),
     clientSecret: z.string().trim().min(1).max(1024).optional(),
     orgId: z.string().trim().min(1).max(255).optional(),
+    dataCenter: z.string().trim().min(1).max(32).optional(),
   })
   .strict()
   .refine(
@@ -220,7 +223,8 @@ export const updateCredentialByIdBodySchema = z
       data.domain !== undefined ||
       data.clientId !== undefined ||
       data.clientSecret !== undefined ||
-      data.orgId !== undefined,
+      data.orgId !== undefined ||
+      data.dataCenter !== undefined,
     {
       message: 'At least one field must be provided',
       path: ['displayName'],

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

@@ -15,14 +15,20 @@
 export const CLIENT_CREDENTIAL_ACCOUNT_SECRET_TYPE = 'client_credential_account' as const
 
 /** Contract field ids a client-credential connect modal collects. */
-export type ClientCredentialAccountFieldId = 'clientId' | 'clientSecret' | 'orgId'
+export type ClientCredentialAccountFieldId = 'clientId' | 'clientSecret' | 'orgId' | 'dataCenter'
 
 export interface ClientCredentialAccountField {
   id: ClientCredentialAccountFieldId
   label: string
   placeholder: string
   /** Rendered with SecretInput and never echoed back. */
   secret: boolean
+  /**
+   * Field the connect modal may submit empty; excluded from
+   * {@link CLIENT_CREDENTIAL_ACCOUNT_REQUIRED_FIELDS} so create/reconnect
+   * validation never demands it. Omitted (default) means required.
+   */
+  optional?: boolean
   /** Soft-format hint shown while the current value doesn't match `hintPattern`. */
   hintPattern?: RegExp
   hintMessage?: string
@@ -116,6 +122,66 @@ export function normalizeZohoDeskSoid(rawOrgId: string): string {
 /** A normalized `soid`: a service-name prefix plus a numeric Zoho org id. */
 export const ZOHO_DESK_SOID_REGEX = /^[A-Za-z]+\.\d+$/
 
+/**
+ * Zoho data centers the Self Client (client-credentials) flow supports. Each
+ * entry pairs the accounts server that mints the token with the Desk REST host
+ * in the same region, so the minter never has to guess either one.
+ *
+ * Only regions where BOTH hosts are confirmed are listed. CA, SA, JP, CN, and
+ * UK are deliberately absent: Zoho's accounts documentation and Zoho's own Desk
+ * SDK disagree on Canada (`accounts.zohocloud.ca` vs `accounts.zoho.ca`), and
+ * the Desk hosts for the others are not confirmed. More regions can be added
+ * once both the accounts server and the Desk host are confirmed for them.
+ *
+ * This applies to the service account only — the interactive OAuth flow's
+ * authorize/token URLs are static per provider and remain US-only.
+ */
+export const ZOHO_DESK_DATA_CENTERS = {
+  us: { accountsBase: 'https://accounts.zoho.com', deskBase: 'https://desk.zoho.com' },
+  eu: { accountsBase: 'https://accounts.zoho.eu', deskBase: 'https://desk.zoho.eu' },
+  in: { accountsBase: 'https://accounts.zoho.in', deskBase: 'https://desk.zoho.in' },
+  au: { accountsBase: 'https://accounts.zoho.com.au', deskBase: 'https://desk.zoho.com.au' },
+} as const satisfies Record<string, { accountsBase: string; deskBase: string }>
+
+export type ZohoDeskDataCenterId = keyof typeof ZOHO_DESK_DATA_CENTERS
+
+/** Region used when the admin leaves the field blank, so existing credentials are unaffected. */
+export const DEFAULT_ZOHO_DESK_DATA_CENTER: ZohoDeskDataCenterId = 'us'
+
+export const ZOHO_DESK_DATA_CENTER_IDS = Object.keys(
+  ZOHO_DESK_DATA_CENTERS
+) as ZohoDeskDataCenterId[]
+
+/** Accepts exactly the supported region codes, case-insensitively after normalization. */
+export const ZOHO_DESK_DATA_CENTER_REGEX = new RegExp(`^(${ZOHO_DESK_DATA_CENTER_IDS.join('|')})$`)
+
+/**
+ * Normalizes a pasted data-center value to its lowercase region code. Shared by
+ * the connect modal's format hint and the server-side minter so both judge the
+ * same normalized value.
+ */
+export function normalizeZohoDeskDataCenter(rawDataCenter: string): string {
+  return rawDataCenter.trim().toLowerCase()
+}
+
+/**
+ * Resolves a stored data-center value to its accounts/Desk host pair. A blank,
+ * absent, or unrecognized value falls back to {@link DEFAULT_ZOHO_DESK_DATA_CENTER}
+ * so credentials created before this field existed keep minting against the US
+ * accounts server exactly as they did.
+ */
+export function resolveZohoDeskDataCenter(rawDataCenter?: string): {
+  id: ZohoDeskDataCenterId
+  accountsBase: string
+  deskBase: string
+} {
+  const normalized = normalizeZohoDeskDataCenter(rawDataCenter ?? '')
+  const id: ZohoDeskDataCenterId = Object.hasOwn(ZOHO_DESK_DATA_CENTERS, normalized)
+    ? (normalized as ZohoDeskDataCenterId)
+    : DEFAULT_ZOHO_DESK_DATA_CENTER
+  return { id, ...ZOHO_DESK_DATA_CENTERS[id] }
+}
+
 export const CLIENT_CREDENTIAL_ACCOUNT_DESCRIPTORS: Record<
   ClientCredentialAccountProviderId,
   ClientCredentialAccountDescriptor
@@ -237,25 +303,36 @@ export const CLIENT_CREDENTIAL_ACCOUNT_DESCRIPTORS: Record<
         hintMessage:
           'Paste the numeric Zoho Desk organization ID from Setup → Developer Space → API, or the full ZohoDesk.<orgId> value.',
       },
+      {
+        id: 'dataCenter',
+        label: 'Data center',
+        placeholder: 'us',
+        secret: false,
+        optional: true,
+        hintPattern: ZOHO_DESK_DATA_CENTER_REGEX,
+        hintNormalize: normalizeZohoDeskDataCenter,
+        hintMessage: `Enter one of ${ZOHO_DESK_DATA_CENTER_IDS.join(', ')}. Leave blank for us (accounts.zoho.com).`,
+      },
     ],
     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.',
+      'Create the Self Client in the Zoho API Console, add the Zoho Desk scopes, and use the organization ID from Setup → Developer Space → API. Self Clients work with the US, EU, IN, and AU data centers — leave the data center blank for US. Zoho Desk triggers still require an OAuth connection, which is US-only.',
   },
 }
 
 /**
  * Required contract fields per client-credential provider, consumed by the
  * `createCredentialBodySchema` superRefine so validation errors name the exact
- * missing field. Derived from each descriptor's field list.
+ * missing field. Derived from each descriptor's field list, minus the fields
+ * marked `optional`.
  */
 export const CLIENT_CREDENTIAL_ACCOUNT_REQUIRED_FIELDS: Record<
   string,
   ClientCredentialAccountFieldId[]
 > = Object.fromEntries(
   Object.values(CLIENT_CREDENTIAL_ACCOUNT_DESCRIPTORS).map((descriptor) => [
     descriptor.providerId,
-    descriptor.fields.map((field) => field.id),
+    descriptor.fields.filter((field) => !field.optional).map((field) => field.id),
   ])
 )