fix(docs): point the service-account guides at the real connect flow (#6277)

waleedlatif1 · web-flow · commit a3a887ad5a07 · 2026-08-04T20:07:03.000-07:00
* 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
"&lt;Service&gt; 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.
diff --git 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
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -73,12 +73,12 @@ If you're not on an Enterprise plan, a personal access token works identically o
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -61,12 +61,12 @@ The API key is bearer credentials for your Attio workspace. Treat it like a pass
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -45,12 +45,12 @@ The API key carries the full privileges of the user who created it — there is
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -45,12 +45,12 @@ The API token carries the creating user's full access to every workspace they be
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -140,15 +140,15 @@ Once Google Cloud and Workspace are configured, add the service account as a cre
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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**
 
     <div className="flex justify-center">
       <Image
         src="/static/credentials/integrations-service-account.png"
-        alt="Integrations page showing Google Service Account"
+        alt="Google Drive integration page with the service-account connect option"
         width={800}
         height={150}
         className="my-4"
@@ -171,7 +171,7 @@ Once Google Cloud and Workspace are configured, add the service account as a cre
     Give the credential a display name (the service account email is used by default)
   </Step>
   <Step>
-    Click **Save**
+    Click **Add service account**
   </Step>
 </Steps>
 
diff --git 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
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -45,12 +45,12 @@ The API key carries the creating user's full access to your Linear workspace. Tr
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -61,12 +61,12 @@ There is no scope picker: personal API tokens carry **all** API permission scope
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -78,12 +78,12 @@ A valid secret with no page connections validates fine in Sim but returns `404 o
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -72,12 +72,12 @@ Use the permanent `.myshopify.com` domain — for example, `your-store.myshopify
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -58,12 +58,12 @@ Newer Trello tokens start with `ATTA`; older ones are 64-character hex strings.
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -43,12 +43,12 @@ The token carries the full permissions of the user who created it — there is n
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -52,12 +52,12 @@ Site tokens expire after **365 consecutive days of inactivity**. Any API call re
 
 <Steps>
   <Step>
-    Open your workspace **Settings** and go to the **Integrations** tab
+    Open **Integrations** from your workspace sidebar
   </Step>
   <Step>
-    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 */}
   </Step>
   <Step>
     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
@@ -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,
