This article covers connecting Activate to HaloPSA specifically. For a complete walkthrough of Activate — the dashboard, working a prospect end-to-end, and creating tenants — see the Activate: A Guide for MSP Partners article.

You will need:

- An administrator account in HaloPSA with permission to manage API applications.

- Administrator access to the Activate section in Hatz.

The procedure typically takes ten to fifteen minutes.

Connecting HaloPSA requires three values: a Tenant URL, a Client ID, and a Client Secret. The Tenant URL identifies your HaloPSA instance; the Client ID and Client Secret are generated by HaloPSA when you create an OAuth application. You will create a dedicated OAuth application, scope it to read your client list, and enter the resulting credentials in Hatz.

1. In HaloPSA, navigate to Configuration → Integrations → Halo PSA API → Applications. (The exact path may vary slightly by HaloPSA version. If your menu differs, locate the section where OAuth applications are managed.)

2. Click New to create a new application.

3. Enter the following:

- Application Name: a descriptive value such as Hatz Activate Integration.

- Active: enabled.

- Authentication Method: Client ID and Secret (Services).

4. Save the application. HaloPSA will reveal the Client ID and provide a View Client Secret action.

▎ Important: The Client Secret should be treated as a password. Record both the Client ID and Client Secret in a secure location, such as a password manager. If the Client Secret is lost, it can be regenerated from within the application record, but any other integrations using the previous value will need to be updated.

Activate requires read access to your client list. Hatz recommends restricting the application to the minimum permissions required.

1. With the application still open, locate the Login Type (or Agent to log in as) setting.

2. Select a dedicated agent or permission level with read-only access to clients. If your organization does not have one, create an agent with read access to the Customers area and assign it here.

3. Locate the Permissions tab and grant the application read access to Clients. Leave all write, edit, and delete permissions disabled. Activate does not write to HaloPSA under any circumstance.

4. Save the application.

The Tenant URL is the hostname at which your HaloPSA instance is reachable. For HaloPSA-hosted tenants, this is typically yourcompany.halopsa.com. For self-hosted installations, this is the hostname of your HaloPSA installation, for example halo.example.com.

Enter only the hostname. Do not include a protocol prefix (https://), a path, or a trailing slash. If you are uncertain which hostname to use, the URL you use to sign in to HaloPSA in your browser is the same hostname.

1. In Hatz, open Activate from the administrator navigation.

2. Click Connect a PSA.

3. Select HaloPSA.

4. Enter the following values:

Hatz validates the credentials against HaloPSA immediately. Activate first exchanges your Client ID and Client Secret for an access token, then queries your client list. Once validated, the initial customer sync begins, and imported records will appear in the Activate customer table within a few seconds.

Note that Activate imports only clients in HaloPSA whose Inactive flag is false. Inactive clients are not imported.

"Tenant_url could not be parsed. Use something like acme.halopsa.com."

The Tenant URL field must contain only the hostname. Remove any protocol prefix, path, or trailing slash, and retry.

"Failed to reach Halo PSA. Check tenant URL."

Activate was unable to reach the hostname provided. Confirm that the Tenant URL is correct and that the HaloPSA instance is reachable from the public internet. If your HaloPSA instance is restricted to

specific IP ranges, please contact Hatz Support for the addresses to allow.

"Halo PSA rejected the credentials. Verify client_id and client_secret."

HaloPSA refused the OAuth token exchange. Please verify the following, in order:

1. The Client ID and Client Secret are exact, case-sensitive copies of the values displayed in HaloPSA, with no leading or trailing whitespace.

2. The application created in Step 1 is marked Active.

3. The Authentication Method on the application is set to Client ID and Secret (Services).

"Halo PSA token was rejected by the Client API."

HaloPSA issued an access token but refused to return your client list. This typically indicates a permissions gap on the application. Confirm that the application has read access to Clients as described in Step 2, and that the agent or permission level assigned to it is not itself restricted from viewing customers.

"Halo PSA token exchange failed." or "Halo PSA client list failed."

HaloPSA returned an unexpected response. This is typically transient. Please retry, and contact Hatz Support if the error persists, including the approximate time of the failed attempt.

Customers were imported without primary contact details.

This is expected behavior in some cases. Activate retrieves the main contact for each client's main site. Clients whose main site has no main contact, or whose main contact has no email address, will appear in Hatz with blank contact fields. These values can be supplied later via CSV import.

A known client is not appearing in Hatz.

Confirm in HaloPSA that the client's Inactive flag is unchecked. Inactive clients are excluded from the import by design.

To rotate the Client Secret:

1. In HaloPSA, open the application record and regenerate the Client Secret.

2. In Hatz, revoke the existing credential from the Activate credentials list.

3. Connect again using the procedure in Step 4 with the new Client Secret.

To revoke Hatz's access:

1. In Hatz, revoke the credential from the Activate credentials list.

2. In HaloPSA, mark the application as inactive or delete it.

On each sync, Activate requests one category of information from HaloPSA:

- Active clients, including each client's main site main contact name and email address, and website.

The following fields are persisted in Hatz: client name, website domain, main contact name, main contact email, and the HaloPSA client identifier. No other HaloPSA data is stored. Credentials are encrypted at rest, and Activate never creates, modifies, or deletes records in HaloPSA.