From a3a887ad5a075b721e09ff04b7d23c51dfee6b3b Mon Sep 17 00:00:00 2001 From: Waleed Date: Tue, 4 Aug 2026 20:07:03 -0700 Subject: [PATCH] fix(docs): point the service-account guides at the real connect flow (#6277) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(docs): point the service-account guides at the real connect flow Fourteen of the twenty service-account guides sent admins to a workspace Settings → Integrations tab that does not exist — Integrations is a top-level workspace route, and there is no integrations section in the settings navigation at all. The same fourteen then told them to search the catalog for " Service Account", a name no catalog entry has: the list is derived from blocks, so the entries are "Airtable", "Monday", "Wealthbox", and search matches only name and description. Both steps now match the six guides that were already correct (Box, Zoho Desk, Zoom, Salesforce, Pipedrive, Atlassian), so all twenty describe one flow. The per-guide connect labels were already right and are untouched. Google needed a third fix: its final step said Click **Save**, but the modal's primary button is `Add {connectNoun}`, which for Google falls back to "Add service account". It also has no catalog entry of its own, so the search now points at Google Drive with a note that any Google integration works. Also adds `invalidCredentialsHelp` for Wealthbox. Its validator rejects a token that works only over Wealthbox's documented ACCESS_TOKEN header, because Sim's tools authenticate with Bearer — a deliberate, documented limitation whose reason reached the server log and never the user, who saw only "Double-check it". * fix(docs): make the Wealthbox rejection copy true for every failure path `invalidCredentialsHelp` replaces the generic message for every `invalid_credentials` rejection, and the Wealthbox validator raises that code on three paths: a 402 expired trial, a 401/403 where both header styles fail, and a 401/403 where Bearer fails but the ACCESS_TOKEN probe succeeds. The copy described only the third, so two of the three told the user their token was valid and pointed at remediation that could not help. Now leads with what is checkable in all three cases and makes the Bearer note conditional on the one signal that distinguishes it — the token working elsewhere. --- .../docs/en/integrations/airtable-service-account.mdx | 6 +++--- .../docs/en/integrations/asana-service-account.mdx | 6 +++--- .../docs/en/integrations/attio-service-account.mdx | 6 +++--- .../docs/en/integrations/calcom-service-account.mdx | 6 +++--- .../docs/en/integrations/clickup-service-account.mdx | 6 +++--- .../docs/en/integrations/google-service-account.mdx | 8 ++++---- .../docs/en/integrations/hubspot-service-account.mdx | 6 +++--- .../docs/en/integrations/linear-service-account.mdx | 6 +++--- .../docs/en/integrations/monday-service-account.mdx | 6 +++--- .../docs/en/integrations/notion-service-account.mdx | 6 +++--- .../docs/en/integrations/shopify-service-account.mdx | 6 +++--- .../docs/en/integrations/trello-service-account.mdx | 6 +++--- .../docs/en/integrations/wealthbox-service-account.mdx | 6 +++--- .../docs/en/integrations/webflow-service-account.mdx | 6 +++--- .../lib/credentials/token-service-accounts/descriptors.ts | 2 ++ 15 files changed, 45 insertions(+), 43 deletions(-) diff --git a/apps/docs/content/docs/en/integrations/airtable-service-account.mdx b/apps/docs/content/docs/en/integrations/airtable-service-account.mdx index b944379097..c2d116d1b9 100644 --- a/apps/docs/content/docs/en/integrations/airtable-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/airtable-service-account.mdx @@ -69,12 +69,12 @@ Enterprise organizations can enable "Block API access to organization-owned base - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Airtable Service Account" and click it, then click **Add to Sim** and choose **Add personal access token** + Search for "Airtable" and open it, then click **Add to Sim** and choose **Add personal access token** - {/* TODO(screenshot): Integrations page with "Airtable Service Account" in the service list */} + {/* TODO(screenshot): Airtable integration page with the service-account connect option */} Paste the **Personal access token**, and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/asana-service-account.mdx b/apps/docs/content/docs/en/integrations/asana-service-account.mdx index 51501c708b..92031bb0b6 100644 --- a/apps/docs/content/docs/en/integrations/asana-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/asana-service-account.mdx @@ -73,12 +73,12 @@ If you're not on an Enterprise plan, a personal access token works identically o - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Asana Service Account" and click it, then click **Add to Sim** and choose **Add access token** + Search for "Asana" and open it, then click **Add to Sim** and choose **Add access token** - {/* TODO(screenshot): Integrations page with "Asana Service Account" in the service list */} + {/* TODO(screenshot): Asana integration page with the service-account connect option */} Paste the token — service account token or personal access token, both work in the same field — and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/attio-service-account.mdx b/apps/docs/content/docs/en/integrations/attio-service-account.mdx index efb048b172..f4ae2dfc03 100644 --- a/apps/docs/content/docs/en/integrations/attio-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/attio-service-account.mdx @@ -61,12 +61,12 @@ The API key is bearer credentials for your Attio workspace. Treat it like a pass - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Attio Service Account" and click it, then click **Add to Sim** and choose **Add API key** + Search for "Attio" and open it, then click **Add to Sim** and choose **Add API key** - {/* TODO(screenshot): Integrations page with "Attio Service Account" in the service list */} + {/* TODO(screenshot): Attio integration page with the service-account connect option */} Paste the API key and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/calcom-service-account.mdx b/apps/docs/content/docs/en/integrations/calcom-service-account.mdx index 6204ea1101..8ab0393bbc 100644 --- a/apps/docs/content/docs/en/integrations/calcom-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/calcom-service-account.mdx @@ -45,12 +45,12 @@ The API key carries the full privileges of the user who created it — there is - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Cal.com Service Account" and click it, then click **Add to Sim** and choose **Add API key** + Search for "Cal.com" and open it, then click **Add to Sim** and choose **Add API key** - {/* TODO(screenshot): Integrations page with "Cal.com Service Account" in the service list */} + {/* TODO(screenshot): Cal.com integration page with the service-account connect option */} Paste the API key, and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/clickup-service-account.mdx b/apps/docs/content/docs/en/integrations/clickup-service-account.mdx index 4d06900ecb..08adc7e270 100644 --- a/apps/docs/content/docs/en/integrations/clickup-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/clickup-service-account.mdx @@ -45,12 +45,12 @@ The API token carries the creating user's full access to every workspace they be - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "ClickUp Service Account" and click it, then click **Add to Sim** and choose **Add API token** + Search for "ClickUp" and open it, then click **Add to Sim** and choose **Add API token** - {/* TODO(screenshot): Integrations page with "ClickUp Service Account" in the service list */} + {/* TODO(screenshot): ClickUp integration page with the service-account connect option */} Paste the API token (`pk_...`) and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/google-service-account.mdx b/apps/docs/content/docs/en/integrations/google-service-account.mdx index a54d86f038..45af573961 100644 --- a/apps/docs/content/docs/en/integrations/google-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/google-service-account.mdx @@ -140,15 +140,15 @@ Once Google Cloud and Workspace are configured, add the service account as a cre - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Google Service Account" and click **Connect** + Search for "Google Drive" and open it — any Google integration works, since they share one service account — then click **Add to Sim** and choose **Add service account**
Integrations page showing Google Service Account - Click **Save** + Click **Add service account** diff --git a/apps/docs/content/docs/en/integrations/hubspot-service-account.mdx b/apps/docs/content/docs/en/integrations/hubspot-service-account.mdx index ae5a8ac2d0..8506524cb3 100644 --- a/apps/docs/content/docs/en/integrations/hubspot-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/hubspot-service-account.mdx @@ -97,12 +97,12 @@ The access token is bearer credentials for your entire portal, limited only by i - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "HubSpot Service Account" and click it, then click **Add to Sim** and choose **Add private app token** + Search for "HubSpot" and open it, then click **Add to Sim** and choose **Add private app token** - {/* TODO(screenshot): Integrations page with "HubSpot Service Account" in the service list */} + {/* TODO(screenshot): HubSpot integration page with the service-account connect option */} Paste the **Private app access token**, and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/linear-service-account.mdx b/apps/docs/content/docs/en/integrations/linear-service-account.mdx index b8aff4ba08..04983f4b26 100644 --- a/apps/docs/content/docs/en/integrations/linear-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/linear-service-account.mdx @@ -45,12 +45,12 @@ The API key carries the creating user's full access to your Linear workspace. Tr - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Linear Service Account" and click it, then click **Add to Sim** and choose **Add API key** + Search for "Linear" and open it, then click **Add to Sim** and choose **Add API key** - {/* TODO(screenshot): Integrations page with "Linear Service Account" in the service list */} + {/* TODO(screenshot): Linear integration page with the service-account connect option */} Paste the API key (`lin_api_...`) and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/monday-service-account.mdx b/apps/docs/content/docs/en/integrations/monday-service-account.mdx index d65903d43b..72c4acb5e8 100644 --- a/apps/docs/content/docs/en/integrations/monday-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/monday-service-account.mdx @@ -61,12 +61,12 @@ There is no scope picker: personal API tokens carry **all** API permission scope - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "monday.com Service Account" and click it, then click **Add to Sim** and choose **Add API token** + Search for "Monday" and open it, then click **Add to Sim** and choose **Add API token** - {/* TODO(screenshot): Integrations page with "monday.com Service Account" in the service list */} + {/* TODO(screenshot): Monday integration page with the service-account connect option */} Paste the API token and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/notion-service-account.mdx b/apps/docs/content/docs/en/integrations/notion-service-account.mdx index 16c742e921..b0dcf41512 100644 --- a/apps/docs/content/docs/en/integrations/notion-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/notion-service-account.mdx @@ -78,12 +78,12 @@ A valid secret with no page connections validates fine in Sim but returns `404 o - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Notion Service Account" and click it, then click **Add to Sim** and choose **Add integration secret** + Search for "Notion" and open it, then click **Add to Sim** and choose **Add integration secret** - {/* TODO(screenshot): Integrations page with "Notion Service Account" in the service list */} + {/* TODO(screenshot): Notion integration page with the service-account connect option */} Paste the **Internal integration secret**, and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/shopify-service-account.mdx b/apps/docs/content/docs/en/integrations/shopify-service-account.mdx index 7111029a1f..98e97136a0 100644 --- a/apps/docs/content/docs/en/integrations/shopify-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/shopify-service-account.mdx @@ -72,12 +72,12 @@ Use the permanent `.myshopify.com` domain — for example, `your-store.myshopify - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Shopify Service Account" and click it, then click **Add to Sim** and choose **Add admin API token** + Search for "Shopify" and open it, then click **Add to Sim** and choose **Add admin API token** - {/* TODO(screenshot): Integrations page with "Shopify Service Account" in the service list */} + {/* TODO(screenshot): Shopify integration page with the service-account connect option */} Paste the Admin API access token, enter the store domain (e.g. `your-store.myshopify.com`), and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/trello-service-account.mdx b/apps/docs/content/docs/en/integrations/trello-service-account.mdx index 57e3c8f11a..ce3a45487d 100644 --- a/apps/docs/content/docs/en/integrations/trello-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/trello-service-account.mdx @@ -58,12 +58,12 @@ Newer Trello tokens start with `ATTA`; older ones are 64-character hex strings. - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Trello Service Account" and click it, then click **Add to Sim** and choose **Add API token** + Search for "Trello" and open it, then click **Add to Sim** and choose **Add API token** - {/* TODO(screenshot): Integrations page with "Trello Service Account" in the service list */} + {/* TODO(screenshot): Trello integration page with the service-account connect option */} Paste the API token, and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/wealthbox-service-account.mdx b/apps/docs/content/docs/en/integrations/wealthbox-service-account.mdx index 27c927e1c1..d47951f6e1 100644 --- a/apps/docs/content/docs/en/integrations/wealthbox-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/wealthbox-service-account.mdx @@ -43,12 +43,12 @@ The token carries the full permissions of the user who created it — there is n - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Wealthbox Service Account" and click it, then click **Add to Sim** and choose **Add access token** + Search for "Wealthbox" and open it, then click **Add to Sim** and choose **Add access token** - {/* TODO(screenshot): Integrations page with "Wealthbox Service Account" in the service list */} + {/* TODO(screenshot): Wealthbox integration page with the service-account connect option */} Paste the API access token, and optionally set a display name and description diff --git a/apps/docs/content/docs/en/integrations/webflow-service-account.mdx b/apps/docs/content/docs/en/integrations/webflow-service-account.mdx index 7144184797..e87f7bbd5e 100644 --- a/apps/docs/content/docs/en/integrations/webflow-service-account.mdx +++ b/apps/docs/content/docs/en/integrations/webflow-service-account.mdx @@ -52,12 +52,12 @@ Site tokens expire after **365 consecutive days of inactivity**. Any API call re - Open your workspace **Settings** and go to the **Integrations** tab + Open **Integrations** from your workspace sidebar - Search for "Webflow Service Account" and click it, then click **Add to Sim** and choose **Add site token** + Search for "Webflow" and open it, then click **Add to Sim** and choose **Add site token** - {/* TODO(screenshot): Integrations page with "Webflow Service Account" in the service list */} + {/* TODO(screenshot): Webflow integration page with the service-account connect option */} Paste the site API token and optionally set a display name and description diff --git a/apps/sim/lib/credentials/token-service-accounts/descriptors.ts b/apps/sim/lib/credentials/token-service-accounts/descriptors.ts index 3edc89b8fe..b018b08a39 100644 --- a/apps/sim/lib/credentials/token-service-accounts/descriptors.ts +++ b/apps/sim/lib/credentials/token-service-accounts/descriptors.ts @@ -343,6 +343,8 @@ export const TOKEN_SERVICE_ACCOUNT_DESCRIPTORS: Record< docsUrl: 'https://docs.sim.ai/integrations/wealthbox-service-account', helpText: 'Trial accounts cannot use the Wealthbox API; contact Wealthbox support if API Access is missing from your Settings.', + invalidCredentialsHelp: + 'Wealthbox rejected this token. Check that it is still active under API Access in your Wealthbox settings, and that the account is not on an expired trial. If the same token works elsewhere, note that Sim authenticates with a Bearer header — a token Wealthbox accepts only over its ACCESS_TOKEN header is refused here.', }, [PIPEDRIVE_SERVICE_ACCOUNT_PROVIDER_ID]: { providerId: PIPEDRIVE_SERVICE_ACCOUNT_PROVIDER_ID,