Skip to content
Talk to us
All posts

HaloPSA integration setup guide

Picture of Stephen Rudakov By  Stephen Rudakov  ·  3 minute read

This document outlines the required HaloPSA configuration steps to enable integration with Support Fusion. Complete these steps in your HaloPSA instance before configuring the connection in Support Fusion.

Prerequisites

  • HaloPSA instance administrator access
  • Knowledge of HaloPSA agent management and role configuration
  • Understanding of HaloPSA OAuth2 API applications

Step 1: Create or Select Agent for API Integration

This agent account will be used by Support Fusion to authenticate with your HaloPSA instance and perform all integration activities. Any actions performed through the integration (such as creating, updating, or commenting on tickets) will appear in HaloPSA audit logs and activity feeds as being performed by this agent.

1.1 Create New Agent (or Skip to 1.2 to Use Existing Agent)

  1. Navigate to Configuration → Teams and Agents → Agents in HaloPSA
  2. Click +New to create a new agent
  3. Fill in the required fields:
    • Name: Support Fusion Integration (or similar)
    • Email: Use a monitored email address (e.g., support.fusion@yourcompany.com)
    • Role: Select an appropriate role (see Step 1.2 for required permissions)
    • Is an API-only Agent: ☑️ Tick this box to prevent the agent from consuming a user licence
      • Note: API-only agents cannot be used for interactive login but are ideal for integrations
  4. Complete any other minimum required fields for your HaloPSA configuration
  5. Click Save

1.2 Configure Agent Role and Permissions

The agent (whether newly created or existing) must have appropriate permissions to create, read, update and close tickets. You can either:

Option A: Use Existing Role

  • Assign the agent a role that matches other agents in your organisation (e.g., "1st Line Support")
  • This ensures consistent permissions with your team

Option B: Create Dedicated Integration Role If you prefer to create a specific role for the Support Fusion integration:

  1. Navigate to Configuration → Teams and Agents → Roles in HaloPSA
  2. Click +New to create a new role
  3. Configure the following minimum permissions:
    • Tickets Access Level: Read and Modify
    • Customers Access Level: Read and Modify
    • Users Access Level: Read and Modify
    • CRM Access Level: Read Only
    • Assets Access Level: Read and Modify
  4. Save the role
  5. Assign this role to your Support Fusion integration agent

1.3 Limit Customer Access (Optional)

If you only want Support Fusion to sync tickets for specific customers:

  1. Configure customer access limitations within the agent's role definition
  2. This restricts which organisations the API integration can access
  3. Note: Most implementations use full customer access - only restrict if you have specific security requirements

Step 2: Create OAuth2 API Application

2.1 Access HaloPSA API Configuration

  1. Navigate to Configuration → Integrations in HaloPSA
  2. Select HaloPSA API
  3. Note the Resource Server URL displayed on this page - this is your API base URL
    • Format: https://[tenant].halopsa.com/api or your custom domain with /api
    • Save this URL - you'll need it for Support Fusion configuration

2.2 Create New OAuth Application

  1. On the HaloPSA API page, click View Applications
  2. Click +New to create a new OAuth application
  3. You'll see the application configuration screen with multiple tabs

2.3 Configure Details Tab

  1. Application Name: Support Fusion Integration
  2. Authentication Method: Select Client ID and Secret (Services)
    • This enables OAuth2 Client Credentials flow suitable for service-to-service authentication
  3. Login Type: Select Agent
  4. Agent: Select the agent you created or identified in Step 1
  5. CRITICAL: After completing these fields, note or copy:
    • Client ID: Displayed on screen
    • Client Secret: Displayed on screen (may only be shown once)
    • Store these securely - you'll need them for Support Fusion configuration

2.4 Configure Permissions Tab

  1. Click the Permissions tab
  2. In the scope field, enter: all:standard
    • This grants the application access to all resources available to the associated agent
    • Admin-level privileges are excluded for security
    • The integration will inherit the permissions configured in the agent's role

2.5 Save Application

  1. Click Save to create the OAuth application
  2. Verify the Client ID and Client Secret are recorded securely

2.6 Record API Credentials

Make note of the following values - you'll need them for Support Fusion configuration:

  • API URL: The Resource Server URL from Step 2.1 (e.g., https://yourcompany.halopsa.com/api or https://yourcompany.halopsa.com)
  • Client ID: From Step 2.3
  • Client Secret: From Step 2.3
  • Scope: all:standard

Step 3: Configure Support Fusion Integration

Once you have completed the HaloPSA configuration steps above, proceed to configure the integration in Support Fusion:

  1. Navigate to Settings in Support Fusion
  2. Select HaloPSA from the platform dropdown
  3. Enter your configuration details:
    • API URL: Your HaloPSA API URL (e.g., https://yourcompany.halopsa.com/api or just https://yourcompany.halopsa.com)
      • Support Fusion will automatically append /api if not included
    • Client ID: The Client ID from Step 2.3
    • Client Secret: The Client Secret from Step 2.3
    • Scope: Enter all:standard
  4. Click Save Configuration
  5. Click Test Connection to verify the integration

Troubleshooting

Common Issues:

Authentication Failed:

  • Verify the Client ID and Client Secret were copied completely without extra characters
  • Confirm the agent has an appropriate role with required permissions assigned
  • Check that the API URL is correct (with or without /api suffix)
  • Ensure the OAuth application has all:standard scope configured

Permission Denied:

  • Review the agent role permissions match those listed in Step 1.2
  • Verify the agent is assigned to the OAuth application in the Details tab
  • Ensure the agent has access to the customers you're trying to sync
  • Check that "Is an API-only Agent" is ticked if you're not using a licensed agent

Invalid API URL:

  • Use the Resource Server URL displayed in Configuration → Integrations → HaloPSA API
  • For standard HaloPSA instances: https://[tenant].halopsa.com or https://[tenant].halopsa.com/api
  • For custom domains: Use your custom domain with or without /api suffix
  • Ensure there are no extra spaces or characters

Agent Access Issues:

  • Verify the agent has "Read and Modify" access to Tickets, Customers, Users, and Assets
  • Check customer access limitations if sync is failing for specific organisations
  • Ensure the role assigned to the agent has appropriate access levels

Resources: