From 3180179d7f5d9a4a530ed355ab540e299fe3dfcb Mon Sep 17 00:00:00 2001 From: Waleed Latif Date: Tue, 4 Aug 2026 19:50:51 -0700 Subject: [PATCH 1/2] fix(docs): point the service-account guides at the real connect flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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". --- .../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 b944379097d..c2d116d1b9b 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 51501c708ba..92031bb0b68 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 efb048b172d..f4ae2dfc03e 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 6204ea11018..8ab0393bbc1 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 4d06900ecb4..08adc7e2707 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 a54d86f0384..45af5739611 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 ae5a8ac2d05..8506524cb33 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 b8aff4ba08d..04983f4b263 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 d65903d43b8..72c4acb5e8b 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 16c742e9212..b0dcf415125 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 7111029a1fb..98e97136a0c 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 57e3c8f11a0..ce3a45487dd 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 27c927e1c11..d47951f6e14 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 71441847978..e87f7bbd5ef 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 3edc89b8fe4..ca981275329 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. Sim's Wealthbox tools authenticate with a Bearer header, so a token Wealthbox only accepts over its ACCESS_TOKEN header is refused here even though it is valid. Check that the token is active in Wealthbox under Settings, and that the account is not on an expired trial.", }, [PIPEDRIVE_SERVICE_ACCOUNT_PROVIDER_ID]: { providerId: PIPEDRIVE_SERVICE_ACCOUNT_PROVIDER_ID, From 1e3ae6fdee6b5788896e0865cb1ab5cf31618b63 Mon Sep 17 00:00:00 2001 From: Waleed Latif Date: Tue, 4 Aug 2026 20:00:29 -0700 Subject: [PATCH 2/2] fix(docs): make the Wealthbox rejection copy true for every failure path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `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. --- apps/sim/lib/credentials/token-service-accounts/descriptors.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/sim/lib/credentials/token-service-accounts/descriptors.ts b/apps/sim/lib/credentials/token-service-accounts/descriptors.ts index ca981275329..b018b08a39c 100644 --- a/apps/sim/lib/credentials/token-service-accounts/descriptors.ts +++ b/apps/sim/lib/credentials/token-service-accounts/descriptors.ts @@ -344,7 +344,7 @@ export const TOKEN_SERVICE_ACCOUNT_DESCRIPTORS: Record< helpText: 'Trial accounts cannot use the Wealthbox API; contact Wealthbox support if API Access is missing from your Settings.', invalidCredentialsHelp: - "Wealthbox rejected this token. Sim's Wealthbox tools authenticate with a Bearer header, so a token Wealthbox only accepts over its ACCESS_TOKEN header is refused here even though it is valid. Check that the token is active in Wealthbox under Settings, and that the account is not on an expired trial.", + '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,