Halo PSA Setup Guide

This guide walks you through connecting Halo PSA to SuperIT. The integration provides comprehensive client and ticket synchronization, asset management, and real-time webhook support.

Step 1: Gather Halo PSA Information

Before starting the SuperIT configuration, collect these details from your Halo PSA environment:

Required Information

• Tenant URL: Your Halo PSA instance URL (e.g., yourdomain.halopsa.com)
• Resource Server URL: Your Halo PSA API's base URL
• Tenant ID: Your Halo tenant identifier (if applicable)

Finding Your Halo PSA Details

Tenant URL:

• Use your Halo PSA login URL
• Format: https://yourdomain.halopsa.com
• Remove any path components (use base domain only)

Resource Server URL and Tenant ID:

• Found in Configuration → Integrations → HaloPSA API
• This page also lists the Authorisation Server URL
• Tenant ID is sometimes labeled as "Instance ID" or "Database ID" and may be optional depending on Halo configuration

Step 2: Create the Super IT Agent in Halo PSA

SuperIT connects to Halo PSA as a dedicated agent rather than as your own user account. Creating this agent first gives you granular control over what SuperIT can see and do, and a clear audit trail for its API activity.

Create the Agent

1. Navigate to Configuration → Teams & Agents → Agents
2. Click +New to create a new agent profile
3. On the Details tab, set:
   • Username: Super IT
   • Email: A dedicated email address for the integration (e.g., [email protected])
   • Is an API-only Agent: True — restricts this agent to API access only, preventing direct login or UI access
   • Default team: No default team
   • Work hours: 24 hours — keeps the agent available for integrations at all times

Configure Agent Permissions

Navigate to the Permissions tab to define the scope of what this agent can access and do within Halo:

Feature Access:

• Ticket access level: Read and modify — allows updating status, adding notes, and assigning tickets
• Customer access level: Read only
• Assets access level: Read only

Ticket Permissions:

• Can add new tickets: Yes — required for automated issue reporting
• Can view unassigned tickets: Yes
• Can view tickets assigned to other agents: Yes — needed to monitor the overall ticket queue

Asset Type Restrictions:

• Allow use of all asset types: Yes

Type Restrictions:

• Allow use of all ticket types: Yes

Applying Specific Restrictions:

• Apply any additional restrictions on tickets, customers, or ticket types here if there is data SuperIT should not have access to. Broad access is useful for full integration coverage, but restrict anything sensitive per your organization's policies.

• Save the agent

Step 3: Register the Super IT API Application

Create the Application

1. Navigate to Configuration → Integrations → HaloPSA API
2. Click View Applications, then click +New

Configure Application Details

1. Application name: Super IT
2. Active: True
3. Authentication method: Client ID and Secret (Services) — the recommended method for server-to-server integrations like SuperIT

After saving, Halo PSA generates a Client ID and Client Secret.

Configure Login Options

• Login type: Agent
• Agent to log in as: The Super IT agent created in Step 2

This ensures API calls from SuperIT run under the agent's permissions, not an administrator's.

Configure Application Permissions

Click the Permissions tab and select the following scopes:

• all:teams — interact with team-related data
• admin:webhooks — manage webhooks for real-time synchronization
• read:tickets — retrieve ticket details, status, and associated data
• edit:tickets — update status, assign agents, and add notes
• read:customers — access customer profiles and contact information
• read:assets — read asset information

Click Save to finalize the application.

Step 4: Configure SuperIT Connection

Add Halo PSA Connection

1. Log into SuperIT as a manager team member
2. Navigate to PSA → Connections
3. Click Add Connection → Halo PSA
4. Enter connection details:

Connection Information:

• Connection Name: Descriptive name (e.g., "Primary Halo PSA")
• Resource Server URL: From Step 1
• Client ID: From Step 3
• Client Secret: From Step 3
• Tenant ID: Halo tenant ID (if required)

Verify Connection

1. Click Save & Test
2. Connection status shows "Connected" when successful
3. Test shows:
   • ✅ Authentication successful
   • ✅ API access confirmed
   • ✅ Tenant information retrieved
4. Fix any errors before proceeding

Step 5: Initial Synchronization

Start Client Sync

1. From the connection detail page, click Sync Clients
2. Monitor sync progress in the dashboard
3. Sync time depends on number of clients (typically 2-10 minutes)

Verify Client Data

1. Navigate to Clients tab in connection details
2. Verify your Halo clients appear correctly
3. Check client names, status, and contact information

Start Asset Sync (Optional)

1. Click Sync Assets to import client assets
2. Note: Asset sync can take time with large inventories
3. Monitor progress and check for any sync errors

Start Ticket Sync

1. Click Sync Tickets to begin initial ticket import
2. Warning: Initial sync can take time with large ticket volumes
3. Choose sync options:
   • Date Range: Sync tickets from last 30/90 days or all time
   • Client Filter: Sync all clients or specific clients only
   • Status Filter: Include closed tickets or open only

Step 6: Configure Webhooks

Webhooks provide real-time updates when tickets change in Halo PSA.

Manual Webhook Setup

1. In Halo PSA, go to Configuration → Integrations → Webhooks
2. Click +New to create a webhook with these settings:
   • Webhook Name: SuperIT
   • Payload URL: Inbound webhook URL from the Webhooks tab of your SuperIT connection
   • Method: POST
   • Content Type: application/json
   • Authentication: Sign request body with a secret key
   • Secret Key: Webhook secret from the Webhooks tab of your SuperIT connection
   • Signature Header Name: X-Halo-Signature
   • Events: New Ticket Logged, Ticket Updated by Agent, Ticket Updated by User

Test Webhook Delivery

1. Create or update a test ticket in Halo PSA
2. Check SuperIT webhook logs for successful delivery
3. Verify ticket changes appear in SuperIT within seconds

Step 7: Configure Client-Team Links

Link Halo clients to specific SuperIT teams for proper ticket routing.

Create Client Links

1. Navigate to Client Management in your Halo connection
2. For each client, click Link Team
3. Select the appropriate Managed Team
4. Configure sync preferences:
   • Sync Tickets: Enable ticket synchronization
   • Sync Assets: Enable asset synchronization
   • Initial Sync: Choose historical data range

Bulk Client Linking

For multiple clients with similar requirements:

1. Select clients using checkboxes
2. Click Bulk Link Teams
3. Choose target team and common settings
4. Apply to all selected clients

Detailed instructions: Client Management Guide

Step 8: Verification and Testing

Check Sync Status

1. Clients: Verify all expected clients are imported
2. Tickets: Confirm recent tickets appear with correct data
3. Assets: Check asset data if asset sync enabled
4. Sync Logs: Review any warnings or errors in sync history

Test Real-time Sync

1. Create Ticket: Create new ticket in Halo PSA
2. Verify Routing: Confirm ticket appears in correct SuperIT team
3. Update Status: Change ticket status and verify sync
4. Add Notes: Add notes and verify synchronization

Test AI Integration

1. Open Conversation: Start chat with SuperIT about a Halo ticket
2. Ticket Context: Verify SuperIT can access ticket details
3. Status Updates: Test AI-driven ticket status changes
4. Asset Context: Verify SuperIT can access related asset information

Step 9: Optimize Performance

Sync Scheduling

Configure optimal sync timing:

• Real-time: Webhooks for immediate updates (recommended)
• Polling: Every 15 minutes for systems without webhook support
• Hybrid: Webhooks + periodic full sync for data integrity

Performance Tuning

• Batch Size: Adjust sync batch size based on system performance
• Date Filters: Limit historical sync to recent data
• Client Filters: Sync only active clients initially
• Asset Sync: Enable only if asset management is required

What to Expect

Sync Performance

• Initial client sync: 2-10 minutes
• Initial ticket sync: 10 minutes to 2 hours (depends on volume and date range)
• Initial asset sync: 5-30 minutes (if enabled)
• Ongoing sync: Real-time (webhooks) or every 15 minutes (polling)

Data Handling

• Historical tickets: Imported based on selected date range
• Assets: Full asset inventory with relationships
• Attachments: Metadata synced, files remain in Halo
• Custom fields: Standard fields synced automatically

Team Experience

• Halo tickets appear in SuperIT team views
• SuperIT can assist with Halo tickets
• Status changes sync between systems
• Asset context available for better support

Next Steps

1. Configure client-team links for proper ticket routing
2. Set up webhook monitoring for real-time performance
3. Review security settings and safety controls

Getting Help

Common Issues

• Authentication failures: Check the API application's Client ID/Secret and permission scopes, and confirm the agent it logs in as is active
• Sync errors: Verify agent permissions and client access
• Webhook problems: Check endpoint configuration and network access

Support Resources

• Halo PSA troubleshooting guide
• Webhook setup documentation
• SuperIT support team for integration assistance
• Halo PSA support for platform-specific questions

Connection successful? Continue with Client Management to configure ticket routing, or check Webhook Setup for advanced real-time configuration.