docs(auth-providers): add the Freshservice auth provider page (TOO-1967)

[iherdt]

What

Adds /references/auth-providers/freshservice, covering how to register a Freshworks OAuth app and configure the matching custom provider in Arcade.

Why

The optimized Freshservice toolkit ships in monorepo#3676. Freshservice is a bring-your-own-provider integration by necessity, not by preference: Freshworks OAuth endpoints embed the organization domain, and there is no global Freshworks authorization server for Arcade to register a shared app against.

"Connect Freshservice" will never be one click the way Google or Slack is. The page says so at the top rather than letting customers discover it during setup.

What the page documents

Each of these came out of building against a live tenant, and each is a place someone would otherwise lose time:

• The developer portal, not the administrator console. The console creates no OAuth credentials; /api-credentials there redirects away.
• The /org/ path segment is required and fails silently without it. Both endpoints return 200 without it, because they fall through to the admin interface's catch-all route, so a misconfigured provider looks correct and fails only at consent. Freshworks' own documentation shows /org/ on the authorize URL but omits it from the token URL.
• The organization domain and the Freshservice subdomain are separate values and are not guaranteed to match. Auth routes by one, the API by the other, which is why the toolkit needs FRESHSERVICE_SUBDOMAIN even in OAuth mode. The page states that this secret is a routing address, not a credential.
• Scopes are granular per sub-resource. tickets.view does not cover ticket conversations or tasks. Requesting only parent scopes reaches consent and then fails at runtime as a permissions error.
• Three reads sit behind write scopes: agents have no .view scope, groups have no read scope at all, and the service catalog's list endpoints need service_catalog.edit. Each forces the same choice between reduced capability and granting a write scope to perform a read.
• Every authorization failure reports invalid_request, never invalid_scope, so a wrong scope, redirect URI, and client id are indistinguishable. The page says to change one variable at a time.

It also states plainly that Freshservice is not Freshdesk. They are separate products with separate APIs and separate toolkits, and neither supersedes the other.

Scope note

The integration page at /resources/integrations/customer-support/freshservice and its sidebar entry are generated by generate-toolkit-docs.yml from the Engine API plus the design system, so they are deliberately not hand-written here. The catalogue entry that feeds that generation is monorepo#3700.

This page does not link to that integration page yet, because broken-link-check resolves toolkit routes against toolkit-docs-generator/data/toolkits/<slug>.json and freshservice.json does not exist until the generator runs. The generated summary links back to this page on its own, since the generator treats each auth-provider page as the source of truth for scopes.

Freshservice is also not added to the provider catalog on the auth-providers index, matching Zendesk and Cisco Duo: that catalog lists Arcade's built-in default providers, and Freshservice cannot be one.

Verification

• vale on the new page: 0 errors, 3 warnings, 5 suggestions. The warnings are Google.Headings reading the proper noun "Freshservice" as title case. For comparison on the same rules: Zendesk 8 warnings, Cisco Duo 12, PagerDuty 5.
• pnpm lint (ultracite): clean, 327 files
• pnpm test: 863 tests passing, including broken-link-check

Note: pnpm vale:check over all of app/en/ currently aborts on a pre-existing MDX parse error in app/en/build/arcade-deploy/page.mdx (unclosed <Steps>), unrelated to this change. I ran Vale against the new file directly.

---

Note

Low Risk
Documentation-only change with no runtime, auth, or API behavior modifications.

Overview
Adds a new Freshservice auth provider reference at /references/auth-providers/freshservice, aimed at operators who must bring their own Freshworks OAuth app (Arcade cannot host a shared provider because OAuth URLs are per-organization).

The page walks through developer-portal app registration, org-domain vs. Freshservice subdomain (FRESHSERVICE_SUBDOMAIN), Dashboard custom provider fields (including the required /org/ OAuth paths), scope guidance for the read-only toolkit, and Python/JS app auth plus MCP custom-tool examples. It also calls out Freshservice vs. Freshdesk and common Freshworks OAuth pitfalls.

public/llms.txt is regenerated to list the new doc URL for LLM indexing.

^{Reviewed by Cursor Bugbot for commit 0b9e025. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 28, 2026 11:31pm