Why a separate agent
A Freshservice API key can do everything its agent can. If you paste your own key, and you're an administrator, the import could do anything you can. A dedicated agent with a narrow role limits what a mistake, or a leaked key, could ever touch.
- Every ticket, update and reply the import makes shows that agent's name, so you can find them later.
- You can switch the agent off the moment the load is finished, which revokes its key.
Set it up
You need to be a Freshservice admin to do this. Menu names may differ slightly between Freshservice plans.
- Create a role. In Freshservice go to Admin → User Management → Roles → New Role, choose an agent role, and name it something like Bulk import. Give it only the permissions for the import types you'll run (see the table below), and leave everything else off.
- Create the agent. Go to Admin → User Management → Agents → New Agent. Use an address you control, such as
bulk-import@yourcompany.com. Give it the role you just made, with the scope Across all groups in the service desk, so it can work on every ticket in the sheet. An agent normally uses a Freshservice licence while it's active. - Add it to the right workspace if you use more than one, so the import can see that workspace's ticket form and catalog.
- Get its API key. Sign in to Freshservice as that agent (use a private browser window), open Profile settings, and copy the API key.
- Paste it into the tool and click Test connection & load workspaces. Then fetch the form or service item. If either gives a permission error, see Fix a 403.
The tool never stores the key on our servers. It's kept in the page while you work and forgotten when you reload, unless you tick Remember the API key until this tab is closed.
Permissions by import type
Permission names as they appear on the Freshservice role page. All need the scope Across all groups in the service desk.
| What you're doing | Role permissions |
|---|---|
| Connect and download a template | Tickets: View tickets. Listing workspaces also needs the admin permission Manage workspace details and status; without it the tool uses the primary workspace. |
| New tickets | Tickets: View tickets (this includes creating them). |
| Update and close tickets | Tickets: View tickets and Edit ticket properties. |
| Close service requests with no description | An Account Admin key. Freshservice won't close a ticket without a description, so the tool retries once skipping mandatory fields, which only an admin may do. Use a temporary admin agent just for this and deactivate it straight after. |
| Replies | Tickets: View tickets and Reply to a ticket. Replies go out from your helpdesk to customers. |
| Service requests | Tickets: View tickets, and the service catalog item must be visible to the agent. |
| Group and "Assigned to" checks (optional) | Admin: View agents and agent groups. Without it the tool skips these checks and Freshservice reports any mismatch when sending. |
Every Freshservice setup is a little different. Test with a few rows first, then widen the role only if Freshservice refuses something.
Fix a 403: "This API key doesn't have permission"
Freshservice answers 403 when the key works but its agent isn't allowed to do what was asked. The tool stops the run straight away, because every other row would fail the same way. Nothing in the stopped row was created.
- Check which import type you were running, and find it in the table above.
- In Freshservice, open the agent's role and add the missing permission. Check the agent's scope is Across all groups in the service desk, and that it's in the right workspace.
- Back in the tool, click Send next batch again. Rows already sent are skipped.
A 401 is different: the key itself is wrong or the agent is deactivated. Copy the key again from the agent's profile.
After the load
- Deactivate the agent in Admin → User Management → Agents. Its API key stops working at once and its licence is freed. Tickets it created keep its name.
- Rotate the key if you think it was exposed (shared in a chat, saved in a file): reset it in the agent's profile, or deactivate the agent.
- Download the row → ticket report from step 5 of the tool before you clear your browser, so you have a record of what was sent.
Questions? Contact support.
