Skip to main content

Freshservice integration setup guide

Covers the Freshservice configuration you need to complete before setting up the integration in Support Fusion.

This guide covers the Freshservice configuration you need to complete before setting up the integration in Support Fusion.

Prerequisites

  • Administrator access to your Freshservice instance.

  • Familiarity with Freshservice role and permission management.

Step 1: Create a custom admin role

Create a cut-down admin role specifically for the integration. Freshservice's built-in admin roles include far more permissions than the integration needs - a dedicated role limits access to only what's required.

  1. Navigate to Admin > User Management > Roles and click New Role.

  2. Give the role a clear name, such as Support Fusion Integration Admin Role.

  3. Enable only the following permissions:

    • View Agents and Agent groups

    • View roles

    • View Requesters

    • View Department

  4. Save the role.

Step 2: Create an integration user

Create a dedicated integration user. Unlike a regular agent, an integration user doesn't consume an agent licence, can't log in to the Freshservice portal, and logs all API activity under a distinct name you can audit.

  1. Navigate to Admin > User Management > Integration Users and click New Integration User.

  2. Set the Display name to something identifiable, such as Support Fusion, and optionally add a Description.

  3. Click Save. The integration user record opens.

Step 3: Assign permissions

Assign both roles to the integration user. The integration needs the IT Agent role for ticket read/write access and the custom admin role for user and field lookups.

  1. On the integration user record, click Edit. If your instance has multiple workspaces, click Add to workspace instead and select the relevant one.

  2. Under Roles, click + Add role and add both:

    • IT Agent (covers ticket read/write across all groups)

    • Support Fusion Integration Admin Role (from Step 1, covers user and field lookups)

  3. Click Save.

Note: Integration users can't be assigned to specific agent groups. Both roles apply across all groups in the workspace automatically.

Step 4: Copy the API key

The API key is available directly from the integration user record - you don't need to sign in as the user to retrieve it.

  1. On the integration user record, find the API key card.

  2. Click the Show icon to reveal the key, then click Copy.

  3. Store the key securely.

Important: If you reset the API key, the integration will stop working until you update it with the new key in Support Fusion.

Next steps

With Freshservice configured, set up the integration in Support Fusion from Settings: choose Freshservice, then enter your instance URL (for example https://acmecorp.freshservice.com) and the API key. Don't add /api to the URL, as Support Fusion appends it automatically. Save the configuration and test the connection. For the per-relationship settings, see Freshservice integration.

Troubleshooting

Authentication failed. Check that the key was copied in full and that the integration user is active.

Permission denied. Confirm the IT Agent role and the custom admin role are both assigned within the workspace.

Invalid API URL. Use the full URL including https://, with no /api or extra path, and check it matches your Freshservice login page.

Connection timeout. Confirm your instance is reachable from the internet, that no IP or firewall rules block Support Fusion, and that your subscription is active.

Did this answer your question?