Skip to content
TidyKB
Free audit

Menu

Security · Freshdesk API access

Read-only by default. Your tickets stay yours.

Freshdesk API keys aren’t scoped: a key can do whatever its agent can. So TidyKB asks for the key of a dedicated agent limited to the knowledge base, keeps that key view-only for ever, and changes nothing until you add a second key with edit rights and confirm the diff in front of you.

01Access

What we access: Solutions endpoints only

This is the whole list of Freshdesk API v2 calls TidyKB may make, paths relative to /api/v2. Every request is matched against it first and refused inside TidyKB if it isn’t on it — a test fails the build if a client method could ever reach anything else.

Not on the list: /tickets · /conversations · /contacts · /companies · every other agent · any DELETE at all

  • GET/agents/meCheck the key is a real agent key
  • GET/settings/helpdeskYour portal languages and the primary one
  • GET/solutions/categories[/{lang}]Walk the knowledge base
  • GET/solutions/categories/{id}/folders[/{lang}]Walk the knowledge base
  • GET/solutions/folders/{id}/subfoldersWalk the knowledge base
  • GET/solutions/folders/{id}/articles[/{lang}]List articles, 100 per page
  • GET/solutions/articles/{id}[/{lang}]Read one article
  • PUT/solutions/articles/{id}[/{lang}]Apply a confirmed change, or undo one
  • POST/solutions/articles/{id}/{lang}Create a translation as a draft

02Agent

A dedicated agent with a knowledge-base-only role

Create an agent such as kb-bot@yourcompany.com, give it a custom role limited to Solutions, and connect its key. You can deactivate it or reset its key in Freshdesk at any time, and TidyKB stops working at once.

Step by step: Freshdesk API key with knowledge-base-only access.

03Writes

How writes work: a second key, a diff, a snapshot, undo

  • Two keysThe key you connect with is view-only and stays that way. Applying a change needs a second key with edit rights, and switching fixes on is a separate action from adding it.
  • PreviewA preview only ever issues GETs — it runs with the view-only key — and shows every change as a diff. You confirm by typing the number of changes it found.
  • Snapshot, then re-readFreshdesk’s API has no versions endpoint and no bulk update, so TidyKB stores each article’s title, body and SEO fields, then re-reads the article and compares it byte for byte immediately before writing. Anything that changed in between is a conflict: skipped, recorded, never overwritten.
  • Live, not draftsFreshdesk has no proven way to stage a draft beside a published article, so TidyKB does not offer one: a job that asks for a draft is refused before a single request. The protection is the diff, the snapshots and undo — not a draft state we can’t deliver.
  • Stop and undoThree unexpected failures in a row stop the batch, with everything written so far still holding its snapshot. Undo puts the stored bytes back, and never forces an article somebody edited after our write.

04Log

Every write leaves a trail you can reverse

The activity log records who turned fixes on, who confirmed which batch and who asked for an undo. Undo restores the whole batch, not only the last edit — and one switch on our side stops every write, undo included, without sending a request.

Sample activity log: a read-only scan of 842 articles, a read-only preview of “Workspace” → “Project” finding 31 changes in 27 articles, the 27 articles written after a confirmation with a snapshot of each one, then all 27 restored from that snapshot with one undo.

05Data

Where your data lives

Servers and the database run at Hetzner in Germany. Both Freshdesk keys are sealed in the database with a public key: the web app can seal a key, it cannot open one. Only the worker that calls Freshdesk holds the private half, and it opens a key in memory for one job. Anywhere in the app, in a log, in an error report or in your account export, a key is only ever its last four characters.

Full details: security measures · subprocessors · DPA

06Disconnect

When you disconnect

Both keys are deleted in the same operation, immediately. The copies of your articles, your scan results and your undo snapshots are kept for 30 days, so reconnecting picks up where you left off and a fix you have not undone yet can still be undone; after that they are deleted automatically. “Delete my data” removes them at once, and closing your account deletes everything with it, from backups as they expire. Undo snapshots are deleted 90 days after the change, and the free audit’s public reports after 90 days.

Security questions

Can TidyKB see our tickets?

No. Every request is matched against the list above before it is sent, and there is no ticket, conversation or contact endpoint on it. With a dedicated agent whose role is limited to the knowledge base, the key can’t reach tickets even if someone tried.

Can TidyKB delete an article?

No. There is no delete endpoint of any kind in the allowlist, for articles, folders or translations. The worst a bug could do is write text we also hold the snapshot for.

What if TidyKB is breached?

Both keys are sealed with a public key that is all the web app holds — it can seal a key, it cannot open one. Only the worker that calls Freshdesk holds the private half, and it opens a key in memory for one job. You can also make a key useless at once by resetting it or deactivating the agent in Freshdesk.

Who works on TidyKB?

One founder, who is the only person with production access. There is no security team and no SOC 2 report yet; the security page says plainly what is and isn’t in place.

Where is article text sent?

Articles are stored on servers in Germany. A scan calls no model at all. Only the articles in a translation batch you start are sent to Anthropic, with their tags and code replaced by placeholders first. The subprocessors page lists every service.