Connect Freshdesk with a KB-only agent

TidyKB connects to Freshdesk with an API key, and a Freshdesk API key carries exactly the permissions of the agent it belongs to. So the whole job is to create an agent that can do one thing — read solution articles — and hand TidyKB that agent's key.

Scanning never needs more than that. Changing articles needs a second, separate key, and that is a later, deliberate step.

What you need

• The Freshdesk domain you sign in to, in the form yourcompany.freshdesk.com.
• An API key from an agent whose role is limited to the knowledge base.
• Nothing else. No app install, no marketplace listing, no call.

Create a knowledge-base-only agent

1. 01

   Add a role limited to Solutions

   In Admin → Team → Roles (older accounts: Admin → Agents → Roles), create a role such as "KB bot" with the permission to view solution articles, and nothing for tickets, contacts, companies or admin settings. Custom roles are not on every Freshdesk plan.
2. 02

   Add an agent for it

   In Admin → Team → Agents, add an agent on a shared mailbox you control, such as kb-bot@yourcompany.com, and give it the new role. Leave its groups empty — it has nothing to do with tickets.
3. 03

   Copy the key

   Sign in as that agent, open Profile settings and click View API key. The key only appears once the agent's email address is verified.

The full walkthrough, with the permission table and a read-only test call you can run yourself first, is in the Freshdesk API key guide.

Connect it in TidyKB

Open Freshdesk connection in the app, paste the domain and the key, and save.

The key is sealed before it is stored, with a public key that is all the web app holds. The web app can seal a key and never open one again; only the worker that talks to Freshdesk holds the private half. After that, the only part of your key the app can ever show you is its last four characters, and the key is never written to a log.

What the connection test does

Saving queues a connection test. It makes a handful of read-only calls and stores three things on the connection:

Your Freshdesk plan is read from the rate-limit header on those responses — 50 calls a minute means Free or trial, 200 Growth, 400 Pro, 700 Enterprise. TidyKB uses at most half of that budget across all of its jobs and leaves the rest to your agents and other apps.

While the test runs, the connection page says so and refreshes itself.

When the test fails

Expected failures are stored as a code on the connection and explained in place, rather than retried forever:

Nothing is written to your help center in any of these cases, because the connection test only reads.

Disconnecting and reconnecting

Disconnect deletes both API keys — the read-only one and the edit key, if you added one — immediately. Nothing that could call Freshdesk survives that click.

What stays for 30 days is the working copy: the articles TidyKB read, the findings, and the snapshots that make undo possible. That is deliberate. A disconnect is exactly the moment somebody might want a bulk replace put back, and deleting the snapshots would destroy an undo you still expect. After 30 days it is deleted automatically.

Delete my data, on the same page, removes the connection and everything under it straight away, before those 30 days are up.

Reconnecting the same help center is a resume, not a fresh start: the articles, snapshots and translation baselines under it were never deleted, so the undo you kept is still there. Connecting a different help center purges the old one immediately instead of waiting.

Freshdesk and Freddy are trademarks of Freshworks Inc. TidyKB is an independent product and is not affiliated with, endorsed or sponsored by any company named on this page.