> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Freshdesk

> Connect Freshdesk to Oleria to discover your help desk agents, their roles, groups, and seat types, and to remove agents or change their roles and groups from Oleria.

Connect Freshdesk to Oleria to see who works in your Freshdesk help desk, which roles and groups they hold, and which kind of agent seat they use. Oleria reads agents, roles, and groups from the Freshdesk API using the API key of a Freshdesk administrator, so you can review help desk access and take action directly from Oleria.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Freshdesk help desk:

* **Accounts** - every agent in the help desk, including support agents, field agents, and collaborators. Each account has the agent's name, email address, job title, creation date, and last login. Agents with the built-in **Administrator** or **Account Administrator** role are marked as administrators. Agents that Freshdesk reports as deactivated are imported as disabled (see [Known limitations](#known-limitations)).
* **Seat types** - each agent's seat: **Full-time support agent**, **Occasional support agent**, **Field agent**, or **Collaborator**. Collaborators are shown with a free license and every other agent with a paid license.
* **Roles** - every built-in and custom Freshdesk role, and the roles each agent holds. An agent can hold several roles.
* **Groups** - every agent group, and the agents who are full members of it.

Oleria also keeps each agent's ticket scope (**Global**, **Group**, or **Restricted**), language, and time zone with the account.

Oleria refreshes this data on its [regular sync schedule](/integrations/overview#sync-model).

<Note>
  Oleria doesn't import tickets, contacts (your customers), companies, knowledge base articles, or any other help desk content. This integration covers identity and access governance for agents, roles, and groups only, so Oleria doesn't populate Access Inventory or resource-level Access Graph data for Freshdesk.
</Note>

## Prerequisites

* A Freshdesk agent with the **Administrator** or **Account Administrator** role. Oleria uses this agent's API key. Freshdesk only lets administrators list agents, roles, and groups.
* Admin access to the Oleria workspace.

<Note>
  Freshdesk API keys have no scopes. The key carries all of its agent's permissions, and Oleria uses the same key for [remediation actions](#remediation-actions). Use a dedicated integration agent rather than an employee's account, so the integration keeps working if that employee leaves or changes roles. The agent uses a Freshdesk agent seat.
</Note>

## Get your API key and domain from Freshdesk

<Steps>
  <Step title="Choose the agent for Oleria">
    Choose or create the agent whose API key Oleria will use, and give it the **Administrator** or **Account Administrator** role. Oleria also reads your Freshdesk account details to identify the help desk. Freshdesk may allow only an **Account Administrator** to read them. Without them, Oleria identifies the help desk by its domain.
  </Step>

  <Step title="Copy the API key">
    Sign in to Freshdesk as that agent, open **Profile settings**, and copy the key shown under **Your API Key**. Store it securely until you've connected Oleria.
  </Step>

  <Step title="Note your Freshdesk domain">
    Note your help desk's Freshdesk domain, for example `acme.freshdesk.com`. If your support portal uses a custom domain such as `support.acme.com`, use the `*.freshdesk.com` name shown in Freshdesk under **Admin** > **Account** > **Helpdesk Rebranding** instead. The Freshdesk API only works through `*.freshdesk.com` domains.
  </Step>
</Steps>

<Note>
  The exact location of these settings can change over time. If the steps above don't match what you see, refer to Freshdesk's own documentation.
</Note>

## Connect Freshdesk to Oleria

<Steps>
  <Step title="Open the integration">
    Go to your Oleria workspace, select **Integrations** -> select **Freshdesk**.
  </Step>

  <Step title="Complete the connection form">
    Select **Continue** and provide the following:

    | Field | Notes |
    | :- | :- |
    | Freshdesk domain | Required. Your help desk's Freshdesk domain, for example `acme.freshdesk.com`. You can also enter just `acme`, or paste a full `https://` address. Custom support domains aren't accepted. |
    | API key | Required. The API key of the agent you chose. |
  </Step>

  <Step title="Confirm the connection">
    Select **Authenticate**. Oleria checks that the key can read its own agent profile, and that it can list agents, roles, and groups. Find the newly connected help desk on the **Connected** tab of your Oleria **Integrations** page.
  </Step>
</Steps>

If **Authenticate** fails, Oleria shows the reason. The most common causes:

* The API key is rejected. Copy the key again from the agent's **Profile settings** and check that it's complete.
* The key's agent isn't an administrator. Give the agent the **Administrator** or **Account Administrator** role, or use another administrator's key.
* Freshdesk answers that the help desk isn't found. Check the spelling of the Freshdesk domain, for example `acme` in `acme.freshdesk.com`.
* Your Freshdesk account's per-minute API limit is used up, for example by other integrations. Try again in a minute.

<Note>
  You can connect each Freshdesk help desk to Oleria once. If you run several help desks, connect each one separately.
</Note>

## Verify the integration

Confirm the Freshdesk help desk appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, you can review the discovered accounts, roles, and groups in your Oleria workspace.

<Note>
  If you rotate the API key, or move the integration to another agent, update the integration in Oleria with the new key. To keep the stored key when you edit the integration, leave the **API key** field empty. The new key and domain must belong to the same Freshdesk account. To change the domain of an existing integration, use a key that can read your account details, such as an **Account Administrator** key, so Oleria can confirm it's the same account. This works only if the integration was first connected with such a key; otherwise Oleria can't confirm the account, and you need to add a new integration for the new domain. To connect a different help desk, add a new integration.
</Note>

## Remediation actions

Oleria can take these actions in Freshdesk. Each one uses the integration's API key, so its agent must keep the **Administrator** or **Account Administrator** role:

* **Remove an agent**. Freshdesk's API has no way to deactivate an agent, so Oleria removes the agent, which turns them into a Freshdesk contact. The user can no longer work in Freshdesk as an agent, their seat is freed, and their assigned tickets become unassigned. Reverting the action turns the contact back into an agent with the seat type, ticket scope, roles, groups, and skills they had before.
* **Add an agent to, or remove an agent from, a role**. Freshdesk replaces an agent's whole list of roles on every change, so Oleria reads the agent's current roles first and keeps every other role unchanged. Reverting the action undoes the change.
* **Add an agent to, or remove an agent from, a group**. Oleria changes the agent's own list of groups and keeps every other group unchanged. Reverting the action undoes the change.

If the agent is already in the requested state, for example already a member of the group, the action succeeds without changing anything.

Keep these limits in mind:

* Oleria won't change the agent whose API key the integration uses, so the integration doesn't lose its own access.
* Oleria won't remove an agent's last role, because Freshdesk requires every agent to have at least one. Assign another role first, or remove the agent.
* Oleria won't remove the only active **Account Administrator**, or take that role away from them. Make another agent an **Account Administrator** first.
* The role or group must exist in the help desk. A role must also suit the agent's type and your plan. If Freshdesk rejects or ignores a role or group change, the action fails and nothing is changed.
* If Oleria can't confirm the result of a change, for example because Freshdesk's response was lost, the action fails with a message saying the change may have been applied. Check the agent in Freshdesk before you run the action again.
* Reverting an agent removal needs a free agent seat. If your account has none, the revert fails with a message saying so. Free or buy a seat and revert again.
* Reverting an agent removal doesn't restore the agent's ticket assignments, view-only group access, or other agent settings such as their signature. Reassign tickets in Freshdesk if needed.
* If the user is already an agent again, or the contact was deleted or merged, reverting an agent removal leaves the user as they are.
* If Freshdesk is slow to show an agent removal, reverting it fails until Freshdesk shows the user as a contact. Try the revert again later.
* If you run an agent removal again after it failed with a message saying the change may have been applied, Oleria may find the user is already a contact and record no change. Reverting that run restores nothing, so restore the agent's roles and groups by hand in Freshdesk.
* If the role or group was deleted from Freshdesk after the action ran, reverting the action restores nothing.
* Freshdesk has no API to reactivate a deactivated agent, so Oleria can't enable an agent. To reactivate one, go to **Admin** > **Team** > **Agents** > **Deactivated** in Freshdesk. To restore an agent that Oleria removed, revert that removal.
* If the key's agent loses its administrator role, syncs fail, and actions fail with a missing-permission error.

## Known limitations

* **No activity.** Freshdesk has no API for its audit log, so Oleria doesn't import sign-ins or administrative changes. Oleria still imports each agent's last login, so dormant account detection works.
* **No MFA, SSO, or password data.** Freshdesk manages these settings in your Freshworks organization, which has no API for them. Oleria shows MFA and SSO status for Freshdesk accounts as unavailable rather than guessing. If you enforce SSO through an identity provider, Oleria shows that through the identity provider's integration.
* **Administrators are identified by built-in role.** Agents are marked as administrators only when they hold the built-in **Administrator** or **Account Administrator** role. Freshdesk doesn't expose the permissions of custom roles, so a custom role that grants admin permissions isn't flagged.
* **Deactivated agents.** Freshdesk doesn't document whether its agent list includes deactivated agents, or how it marks them. Oleria imports an agent as disabled when Freshdesk marks it deactivated; a deactivated agent that Freshdesk leaves out of the list isn't imported.
* **Full group members only.** Agents with view-only access to a group aren't shown as members of it.
* **Last login may not reflect API use.** An agent that only uses its API key, such as the integration's own agent, may look dormant.
* **No API keys, apps, or AI agents.** Freshdesk doesn't list API keys or installed apps, and has no API for Freddy AI agents. An AI agent that runs as a Freshdesk agent appears as an ordinary account.
* **Freshworks organization admins.** Admins of your Freshworks organization who don't hold a Freshdesk agent seat aren't imported.
* **Shared API limit.** Freshdesk limits API requests per minute across your whole account, shared with your other integrations. Oleria paces each sync to about 90 requests a minute, and pauses whenever Freshdesk reports that five or fewer requests remain in the current minute. Remediation actions are paced separately, so a sync and a batch of actions can run at the same time. On plans with a low limit, such as the 50-requests-a-minute trial, Oleria's requests can use up the limit your other integrations share.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.