Connect HaloPSA

HaloPSA is a professional services automation (PSA) platform — the system your MSP uses for tickets, clients, assets, contracts, invoices, and projects. Connecting HaloPSA to StackJack lets your AI assistant (Claude, Copilot, or any other MCP-capable client) read and update that data through StackJack's tool catalog. StackJack passes tool results through as raw HaloPSA API responses, so what your AI sees is exactly what HaloPSA returns.

The HaloPSA integration is StackJack's second-largest tool family (after ConnectWise PSA) — nearly 600 tools (prefix halo_) spanning:

Tool availability depends on your HaloPSA connector plan tier — the in-portal tool selector and the Permissions page (/permissions) show exactly which tools your plan includes.

Choose an authentication method

HaloPSA is one of only two connectors (with NinjaOne) where you choose between two authentication methods in the setup dialog:

• Authorization Code (User OAuth) — recommended. Each team member signs into HaloPSA with their own identity, so ticket updates and audit trails in HaloPSA are attributed to the actual person whose AI session made the change. StackJack maintains the connection automatically with refresh tokens.
• Client Credentials. One shared application identity for the whole team. Simpler to set up, but all activity in HaloPSA is attributed to the API application.

Prerequisites in HaloPSA

You need HaloPSA administrator access to create an API application.

Option A — Authorization Code (User OAuth)

1. In HaloPSA, go to Configuration > Integrations > API Applications and create a new application. Set the authentication method to Authorization Code.
2. Set the application's redirect URI to the StackJack OAuth callback URL shown in the StackJack connector setup form (there is a copy button next to it).
3. On the Permissions tab, enable the permissions required for the tools you want to use (see the permission summary below).
4. Return to StackJack and click Authorize to complete the flow.

Option B — Client Credentials

1. In HaloPSA, go to Configuration > Integrations > API Applications and create a new application. Set the authentication method to Client ID and Secret.
2. On the Permissions tab, enable the permissions required for the tools you want to use.
3. Copy the Client ID and Client Secret from the application details page.
4. Return to StackJack and paste them into the connector setup form.

HaloPSA permissions

HaloPSA API applications use granular permission groups. Enable read (and, where you want write tools, edit) access for the areas you plan to use:

Tip: the StackJack Permissions page (/permissions) maps every StackJack tool to the exact HaloPSA permission it needs, so you can scope the application to least privilege.

Set up the connector in StackJack

1. In the StackJack portal, go to Connectors and find the HaloPSA card.
2. Optional: click How To Connect for the in-portal version of this guide.
3. Click Configure.
4. Fill in the fields:

5. Click Save (Client Credentials) or Authorize (OAuth). In OAuth mode you are sent to HaloPSA to sign in and approve access, then returned to StackJack.

What happens when you save

• Your credentials are stored in Azure Key Vault — never in the StackJack database.
• A Free-tier connector subscription is created automatically if you don't already have one (upgrade any time from the connector card).
• StackJack immediately test-calls your HaloPSA instance (an authenticated "who am I" request). Success shows a confirmation toast; a failed or timed-out test shows a warning toast but does not block the save — StackJack retries validation in the background.
• StackJack proactively refreshes OAuth tokens and re-validates credentials in the background. After 3 consecutive definitive failures the credential is auto-disabled, tool calls stop, and the tenant owner is emailed. The connector card then offers Re-enable and Update Credentials; an invalid-but-enabled card offers Re-test.

If HaloPSA completes the OAuth flow but does not return a refresh token, StackJack refuses to save the connection and shows a missing_refresh_token error — this means the HaloPSA application is missing the offline access / refresh token capability. Fix the application configuration in HaloPSA and authorize again.

Instance URL guidance

There is no region selector — enter your full HaloPSA URL (for example https://yourcompany.halopsa.com). StackJack derives your Halo tenant name from the URL's subdomain and appends API paths automatically; enter only the base URL.

Per-user connections for team members

If you configured HaloPSA with Authorization Code, each team member can connect their own HaloPSA identity:

1. The member signs into StackJack, opens the Connectors page, and finds the HaloPSA card in their Your personal sign-ins section.
2. The HaloPSA card shows Authorization Required with a Connect button. (Members only see the card if they have at least one HaloPSA tool assigned and the connector subscription is active.)
3. Clicking Connect reuses your OAuth application — the member signs into HaloPSA with their own credentials.
4. On success, StackJack automatically creates a personal MCP client key for the member (named "member's HaloPSA key") and shows it once on a one-time credentials page. The member pastes it into their AI client.

From then on, that member's AI activity runs under their own HaloPSA identity. If a member's connection breaks (for example, their refresh token is revoked in Halo), their card shows Re-authorize Required.

When you re-save the shared OAuth application configuration (for example after rotating the client secret in HaloPSA), StackJack automatically cascades the new application settings to every team member's connection while preserving each member's own sign-in — members do not need to reconnect.

Limits and behavior

Troubleshooting

Disconnecting: the Disconnect button deletes the stored credentials from Key Vault and immediately stops all HaloPSA tool calls. Note that disconnecting does not cancel a paid connector subscription — cancel the plan separately from the connector card if you no longer want it.