Freshdesk Integration

Flexivity AI connects to Freshdesk as a cloud-to-cloud integration — there is nothing to install in your own infrastructure, and no inbound firewall rules to open.

Stage 1 covers the connection only. AI features — ticket summaries, recommended resolutions, classification, and knowledge-base gap analysis — are rolling out for Freshdesk in later releases. Your instance page shows every feature with a Coming soon for Freshdesk label until it lands, so you can see what is on the way. Connecting now means those features light up without you setting anything up again.

How Freshdesk Authentication Differs

If you have connected Zendesk before, expect this to feel different.

Freshdesk does not offer OAuth for external API access. Zendesk’s connect flow is a consent screen you click through; Freshdesk has no equivalent for an external service like Flexivity. The Freshdesk API authenticates with an agent API key over HTTP Basic auth, and there is no way to provision one automatically.

The practical consequence is that setup involves copying one value — your integration agent’s API key — from Freshdesk into Flexivity. That is the only value you ever copy. Everything else is a click.

Which Setup Path Applies to You

Freshdesk custom apps require Pro or above, which determines how Flexivity receives your ticket events.

Your Freshdesk plan	Setup path	How events reach Flexivity
Free	Not supported	Freshdesk Free has no API access at all
Growth	Console connect	Flexivity polls Freshdesk on a schedule
Pro	App install	The Flexivity app forwards events as they happen
Enterprise	App install	The Flexivity app forwards events as they happen

On Growth, polling is a plan limitation, not a fault. Your instance page says so plainly rather than showing an error or an unfinished setup step — there is nothing for you to fix, and everything works. If you later upgrade to Pro and install the app, Flexivity switches to direct delivery on its own; you do not reconnect or reconfigure anything.

The Dedicated Integration Agent

Create a Freshdesk agent that exists solely for Flexivity, and use its API key. Do not use your own admin account’s key.

Two things to know before you start, because both cost something and neither is reversible by us:

The integration agent needs the Account Administrator role. Not Administrator, which sounds right and is not — see below.
It occupies a paid Freshdesk agent seat, billed by Freshdesk at your plan’s per-agent rate. Flexivity cannot avoid this, and there is no free tier of Freshdesk agent that can do the job.

This matters more than it might look:

Revoking access does not disturb a person. Deactivating the integration agent cuts Flexivity off cleanly. Revoking your own key breaks whatever else you use it for.
The connection survives staff changes. An API key tied to an employee’s account stops working the day they leave, usually with no warning and no obvious cause.
Actions are attributable. Once later stages start writing notes back to tickets, those actions show as coming from the integration agent rather than appearing as if a colleague did them.

Freshdesk rate limits apply per account, not per API key, so a dedicated agent does not get you extra headroom — but it does make it obvious which integration is consuming it.

Why Account Administrator, specifically

It would be better if the integration agent could hold a narrow role, and we tried. It cannot.

Flexivity confirms a connection by calling GET /api/v2/account, which is how we read the stable account identity that ties your Freshdesk account to your Flexivity instance. Both the initial connect and every later health check depend on that answer.

Freshdesk’s roles do not all reach that endpoint:

Role	Can read tickets	Can read the account
`Agent`	yes	no
`Administrator`	yes	no
`Account Administrator`	yes	yes

Administrator sounds sufficient and is not. It is the obvious choice, and it fails — the agent connects and then reports an error you cannot fix from the Freshdesk side. Assigning Agent and Administrator together does not help either; only Account Administrator reaches the endpoint.

This is a limitation of Freshdesk’s role model rather than a choice on our part. Freshdesk offers no OAuth for external applications and therefore no scopes, so there is no way to grant “read the account identity” without granting the Account Administrator role that carries it.

Do not narrow the integration agent’s role after connecting, including down to Administrator. It is the most common way to break a working connection, and the symptom — an authorization error on a key that is still perfectly valid — does not point at the cause.

Connecting

In Freshdesk, create the dedicated integration agent, give it the Account Administrator role, and note its API key (Profile settings → Your API Key while signed in as that agent).
In app.flexivity.ai , go to Help Desk and create a Freshdesk instance.
Enter your Freshdesk domain — the full yourcompany.freshdesk.com. Vanity domains and custom CNAMEs do not work here: Freshdesk serves its API only from *.freshdesk.com, so Flexivity rejects anything else rather than failing later in a way that is hard to diagnose.
Paste the API key and connect.

Flexivity verifies the key immediately against a single read-only call. If it fails, you get a specific reason rather than a generic error — see Key Rotation and Troubleshooting.

Flexivity stores the key encrypted and never displays it again. Your instance page shows only a masked fingerprint, ending in the last four characters, so you can tell which key is stored without it being recoverable by anyone — including Flexivity support. Support will never ask you for your API key.

Ongoing Health Checks

Every five minutes, Flexivity verifies your stored key against Freshdesk with one read-only account call. It reads no ticket data.

Your instance page reports one of:

State	Meaning
Connected	The last check succeeded recently.
Awaiting check	Either Freshdesk could not be reached on the last attempt, or the last success is old enough that it no longer describes the connection. Usually clears on its own.
Action needed	Your credential needs attention. The page tells you which fix applies.
Not yet verified	Setup is not finished. Nothing has failed.

“Awaiting check” is often just Freshdesk’s shared rate limit. Because that budget covers your whole account, another integration’s busy period can use it up while Flexivity’s credentials are fine — so this deliberately does not present as a broken connection.

Key Rotation and Troubleshooting

You can rotate the API key at any time from your instance page. Flexivity verifies the new key before replacing the old one, so a mistyped key leaves your working connection untouched instead of breaking it.

Rotate when you would rotate any credential: on a schedule, when someone with access leaves, or if you suspect exposure.

When a check fails, the console distinguishes two cases that look similar and are fixed differently:

“Freshdesk rejected the API key” — the key is no longer valid. Usually it was regenerated in Freshdesk, or the integration agent was deactivated. Fix: generate a new key and rotate it here.

“The integration agent’s role does not permit this call” — the key is valid, but the agent no longer holds the Account Administrator role, so it can no longer read the account identity Flexivity checks against. Fix: restore the agent to Account Administrator in Freshdesk — note that plain Administrator is not enough. Rotating the key will not help, because the key was never the problem.

Disconnecting

Disconnecting destroys every stored credential for the instance — the API key and, on Pro+, the app’s signing secret. Nothing is retained.

That means reconnecting later requires a freshly supplied API key. It also means disconnect is a genuine answer to a suspected key compromise, not just a way to pause the integration.