Skip to content
Scopable logoScopable
IntegrationsLast updated: 2026-06-22

Halo PSA Integration Setup Guide

Connect Halo PSA to Scopable and sync clients, sites, contacts, products, assets, opportunities, and contracts through a guided four-step wizard.

Scopable Team7 min read

Prerequisites

  • HaloPSA administrator access (ability to create an API application)
  • Your Halo instance URL (e.g. https://yourcompany.halopsa.com)
  • A Scopable account with admin permissions
  • No active ConnectWise integration (only one PSA can be connected at a time)
  • The Halo PSA integration enabled for your Scopable account

Connecting Halo PSA lets Scopable sync your clients, sites, contacts, products, assets, opportunities, and contracts. You'll create an API application in HaloPSA, then walk through a four-step wizard in Scopable to test the connection, pick what to sync, and kick off your first sync.

One PSA at a time. Scopable connects to a single PSA. If you currently have ConnectWise active, disconnect it first. Scopable blocks activating Halo while ConnectWise is connected, and vice versa. Comparing the two? See ConnectWise vs HaloPSA.

This guide covers the full PSA connection. It's different from the Halo Ticket Namer, which is a separate, optional utility for cleaning up ticket names via webhooks.

What connecting Halo PSA does

Scopable performs a read-only sync (no write-back in this version) of:

  • Clients (always synced; the required foundation)
  • Sites
  • Contacts
  • Products
  • Assets
  • Opportunities
  • Contracts

You can limit the sync to active clients only, and optionally enable webhooks for real-time updates.

Step 1: Create an API application in HaloPSA

  1. In HaloPSA, go to Configuration → Agents.
  2. Create a new agent (e.g. "Scopable API").
  3. Give it an Administrator role (or a role with the permissions your sync needs).
  4. Check API Only Agent so it doesn't consume a license.
  5. Save.

1.2 Create the API application

  1. Go to Configuration → Integrations → HaloPSA API.
  2. On this page, note the three values Halo shows you, which you'll need them in Scopable:
    • Resource Server: your API base URL (e.g. https://yourcompany.halopsa.com)
    • Authorisation Server: the OAuth token host
    • Tenant: present for hosted/multi-tenant Halo instances
  3. Click View Applications, then New.
  4. Configure the application:
    • Name: e.g. "Scopable Integration"
    • Authentication Method: Client ID & Secret (client credentials)
    • Login Agent: the API agent from step 1.1
  5. Open the Permissions tab and grant the permissions your sync needs.
  6. Copy the Client Secret. It's shown only once. Save the Client ID too (it may finalize after the first save).

Understanding the URLs

Halo splits authentication and data across two hosts. Scopable handles this for you, but it helps to know which is which:

  • Resource Server / Base URL: where the API lives. Scopable calls {base-url}/api/....
  • Authorisation Server: where Scopable requests an access token ({auth-server}/auth/token). On most hosted Halo instances this shares the same host as the base URL, and Scopable auto-fills it for you.
  • Tenant: required only for hosted (multi-tenant) Halo. Leave it blank for single-tenant or on-premises instances.

Hosted Halo URLs follow the pattern https://yourcompany.halopsa.com. You can also retrieve your auth server and tenant programmatically from https://yourcompany.halopsa.com/api/authinfo.

Step 2: Open the Halo PSA integration in Scopable

  1. Log in to Scopable as an Admin.
  2. Click Integrations in the left-side navigation under Administration.
  3. On the Halo PSA card (status reads Not Configured), click Connect to launch the setup wizard.

Don't see a Halo PSA tab, or it says it's unavailable? This integration is in gradual rollout. If you see "The Halo PSA integration is currently not available for your account," it isn't enabled yet. Contact your administrator or Scopable. Also confirm you don't have an active ConnectWise integration, which blocks Halo.

Step 3: Step through the setup wizard

Wizard step 1: Connect to Halo PSA

Fill in:

  • Base URL (required): e.g. https://yourcompany.halopsa.com
  • Auth Server (optional): auto-populated from your Base URL; change only if you run a separate auth server
  • Tenant Name (optional): required for multi-tenant hosted Halo; leave blank for single-tenant/on-prem
  • Client ID (required): from your API application
  • Client Secret (required): from your API application (masked; stored encrypted in Scopable's secure vault)

Click Test Connection. Scopable acquires a token and verifies it by reading your agent profile; on success it confirms the connection and names the agent it connected as. You can't continue until the test passes.

Wizard step 2: Select data to sync

Choose which record types to pull. Clients is always on (the others depend on it). Toggle Active clients only to limit the sync to active clients. You can change these selections later from the Data Sync tab.

Wizard step 3: Configure webhooks (optional)

For real-time updates, Scopable shows a Webhook URL to copy. In HaloPSA, go to Configuration → Integrations → Webhooks → New Webhook, paste the URL into the Payload URL field, choose your event types, set the format to JSON, and save. This step is optional; you can skip it and data still syncs on schedule.

Wizard step 4: Review & start

Review the connection summary, the data types you selected, and your webhook status, then click Save & Start Initial Sync. Scopable stores your credentials, activates the integration, and begins the first sync. You're taken to the Halo dashboard, where the Data Sync, Sync Filters, Sync Logs, and Configuration tabs live.

The initial sync may take a few minutes depending on how many records are in your Halo instance.

Troubleshooting

Connection test fails with an authentication error

Your Client ID or Client Secret is wrong. Regenerate the secret in your HaloPSA API application and re-paste both values carefully (no trailing spaces).

Token works but the connection still fails (403)

The API application's agent or role lacks permissions. Open the application's Permissions tab in Halo and grant the access your sync needs.

Hosted instance won't authenticate

For hosted (multi-tenant) Halo, the Tenant Name is required. Fill it in with the Tenant value shown on the HaloPSA API configuration page.

Auth Server vs Base URL mix-up

Token requests go to the Auth Server; data calls go to the Base URL. If you overrode the Auth Server field incorrectly, the token step fails. Leave Auth Server auto-filled unless you genuinely run a separate auth server.

On-premises Halo can't be reached

An on-prem Halo instance must be reachable from the internet, with valid SSL certificates. Connection and token requests time out after about 15 seconds.

"Cannot activate HALO PSA: ConnectWise integration is already active"

Only one PSA can be connected at a time. Disconnect ConnectWise first, then connect Halo.

Still stuck?

Email us at [email protected] with a screenshot of the error and we'll help you get connected.

Frequently Asked Questions

Can I run Halo PSA and ConnectWise at the same time?

No. They're mutually exclusive: only one PSA can be active. Activating Halo is blocked while ConnectWise is connected.

Does Scopable write data back to Halo?

No. This version is a read-only sync from Halo into Scopable.

What gets synced?

Clients, sites, contacts, products, assets, opportunities, and contracts. Clients always sync; the rest are optional. The "Active clients only" toggle limits the sync to active clients.

Do I have to set up webhooks?

No, webhooks are optional. Without them, your data syncs on schedule; with them, you also get real-time updates.

Are my credentials secure?

Yes. The Client Secret is stored in Scopable's encrypted vault and is masked in the interface after entry.

Can I change what's synced later?

Yes. Adjust your data-type selections and filters from the Data Sync and Sync Filters tabs after setup.

Related Resources