About

This module provides a PowerShell interface to the Halo API. It's designed to for PowerShell developers to build their own PowerShell scripts and modules to interact with Halo. It's well tested for Halo Professional Services Automation (PSA) but should work with Halo IT Service Management (ITSM), Halo Service Desk and Halo Customer Relationship Management (CRM).

The module is written for PowerShell 7. It is not compatible with Windows PowerShell 5.1 and there are no current plans to change this. It is tested extensively against HaloPSA instances only - please test against HaloITSM or HaloServiceDesk instances and let us know how it works. The module is licensed under the MIT license.

It covers the Halo Service Solutions products HaloPSA, HaloITSM and HaloServiceDesk.

Installing

This module is published to the PowerShell Gallery. You can install it using the following command:

Install-Module -Name HaloAPI

From time-to-time, preview releases will be published to the PowerShell Gallery. These are not considered stable and should not be used in production. You can install preview releases using the following command:

Install-Module -Name HaloAPI -AllowPrerelease

Getting Started

The first and probably most important requirement for this module is getting it connected to your Halo instance.

HaloAPI supports two ways of authenticating. Both need an API application in Halo, but the application is configured differently:

	Client credentials (default)	Interactive (-Interactive)
Best for	Unattended scripts, scheduled tasks, automation, CI	Hands-on use at a console, ad-hoc admin tasks
Halo Authentication Method	Client ID and Secret (Services)	Authorisation Code (Native Application)
Credentials to retain	Client ID and Client Secret (keep the Client Secret confidential)	Client ID only (no client secret)
Requests run as	The Agent to login as set on the application	The agent who signs in through the browser
Needs a browser	No	Yes, on the machine running PowerShell
Token renewal	Requests a new token with the secret	Refresh token, with a browser sign-in as fallback

If you are scripting something that runs without you at the keyboard, use client credentials. If you want API calls to run with your own permissions (and show up as you in Halo), use -Interactive.

Option 1: Client credentials (unattended)

Creating the client credentials application in Halo

1. In your Halo instance head to Configuration > Integrations > Halo PSA API
   This might be Halo Service Desk API or Halo ITSM API.

2. Select View Applications
   All going well you should be at config/integrations/api/applications.

3. Select New to add a new API application.

4. Enter the Application Name.
   For example HaloAPI PS Module.

5. Make sure you check the Active box.

6. Set the Authentication Method to Client ID and Secret (Services).

7. Store the Client ID and Client Secret securely.

8. Set the Login Type and Agent to login as appropriately.
   This setting determines who appears to be responsible for these API calls. You may want to create a dedicated agent user for this purpose.

9. Select the Permissions tab.

10. Grant the application the permissions required for your purposes.
    You should limit the API to only the permissions it needs to do the job you're scripting for.

Connecting with client credentials

Connect-HaloAPI -ClientID "a1234567-bcd8-9e01-2f34-56g7hijk89lm" -Tenant "demo" -URL "https://demo.halopsa.com" -ClientSecret "a1234567-bcd8-9e01-2f34-56g7hijk89lm-a1234567-bcd8-9e01-2f34-56g7hijk89lm" -Scopes "all"

• -Tenant is only needed for hosted Halo instances. -Scopes defaults to all and is limited by the permissions granted to the application.
• Avoid leaving the client secret in scripts or shell history. Connect-HaloAPI can read and save the URL, client ID and secret in Azure Key Vault using -UseKeyVault, -SaveToKeyVault, -VaultName, -SecretName and (for unattended Azure hosts) -UseManagedIdentity. See the Connect-HaloAPI documentation.

Option 2: Interactive browser sign-in (-Interactive)

Interactive sign-in uses the OAuth authorisation code flow with PKCE. You sign in to Halo in your browser as yourself, so there is no client secret to create, store or leak, and every API call runs with your agent account's permissions.

Creating the interactive application in Halo

1. Go to Configuration > Integrations > Halo PSA API > View Applications and select New, as above.

2. Enter an Application Name, for example HaloAPI PS Module (Interactive), and make sure Active is checked.

3. Set the Authentication Method to Authorisation Code (Native Application).

4. Add http://localhost:8400/ as a Redirect URI.
   It must match the -RedirectURI you connect with exactly, including the trailing slash. The default is http://localhost:8400/.

5. Note the Client ID. There is no client secret for this application type.

6. Save the application.
   What the module can do is limited by the signed-in agent's own permissions in Halo as well as the scopes you request.

Connecting interactively

Connect-HaloAPI -Interactive -URL "https://demo.halopsa.com" -ClientID "a1234567-bcd8-9e01-2f34-56g7hijk89lm" -Tenant "demo"

What happens next:

1. PowerShell starts a short-lived listener on the redirect URI (localhost only) and opens your default browser at the Halo sign-in page. If no browser opens, the URL is printed so you can open it yourself.
2. Sign in to Halo as normal (including any SSO or MFA your instance requires).
3. Halo redirects back to the local listener, the browser shows Signed in to Halo, and you can close the tab. The module exchanges the code for a token and the connection is ready.
4. When a token expires, the module renews it using the refresh token. Batch processing renews within five minutes of expiry so parallel workers can reuse the renewed token rather than prompting separately. If renewal is rejected or there is no refresh token, you are taken through the browser sign-in again.

Interactive-only options:

Parameter	Default	Purpose
-RedirectURI	http://localhost:8400/	Address the local listener binds to. Must match a Redirect URI on the Halo application and end with /. Change it if port 8400 is in use.
-LoginTimeout	300	Seconds to wait for you to finish signing in before giving up.
-Scopes	all	Scopes to request, as with client credentials.

-Interactive can't be combined with -ClientSecret or the Key Vault parameters; those belong to the client credentials flow.

Troubleshooting interactive sign-in

• "Could not listen on ... for the Halo sign-in redirect" - the port is in use or blocked. Pick another port, add it as a Redirect URI on the Halo application, and pass it with -RedirectURI "http://localhost:8401/".
• "RedirectURI must have a trailing slash" - add the / to the end of the URI, both in Halo and in -RedirectURI.
• Halo reports a redirect URI mismatch - the Redirect URI on the application and -RedirectURI must be identical.
• "Timed out ... waiting for the Halo sign-in to complete" - finish the browser sign-in within -LoginTimeout seconds, or increase it.
• Browser doesn't open (remote session, SSH, headless host) - copy the printed URL into a browser on the same machine. The redirect goes to localhost, so the browser must be on the machine running PowerShell. For headless or unattended use, choose client credentials instead.
• "The Halo sign-in response state did not match the request" - the browser returned from a different or stale sign-in attempt. Run Connect-HaloAPI -Interactive again and use the newly opened tab.
• Use -Verbose to see which step is running. Debug output only contains metadata (no tokens or secrets).

Known Issues

Not all Halo's API endpoints have cmdlets but all documented endpoints exist in this module, along with many other undocumented endpoints. Want an endpoint / functionality implemented? Log an issue on GitHub and if possible someone might add it, or you can implement it yourself.

For little used or one-off endpoints you can call Invoke-HaloRequest directly to reuse the same authentication token/connection and run arbitrary requests. See the cmdlet documentation for more information.

Who develops the module?

I am Mikey O'Toole (@homotechsual). I am the director of a UK-based managed IT services provider with a passion for automation and good quality MSP software tools.

PRs and significant code contributions have been provided by Mendy Green @greenlighttec, Robbie Emerson @Robbie-Renada. A full list of contributors can be found in the GitHub repository.

The module was initially co-developed with Luke Whitelock (@LWhitelock).

AI Use

AI is used for code review, automated testing suggestions, and documentation generation (primarily examples or restructuring of documentation) within the development workflow.

PRs and code contributions are reviewed with the assistance of AI tools and automated workflows (described in the development quality gates section) to ensure adherence to coding standards and best practices.

AI tools are not used to make final decisions on code changes; human review and judgment remain essential to maintain code quality and project standards.