Connect HaloPSA to Conduit

This walkthrough connects HaloPSA (PSA) to Conduit. HaloPSA uses OAuth 2.0 Client Credentials — instead of a single API key, you create an API application that issues a Client ID and Client Secret pair, and Conduit exchanges those for short-lived access tokens automatically, refreshing them as they expire.

Menu labels can change

The HaloPSA-portal steps below reflect HaloPSA’s API-application flow at time of writing; menu labels can shift between HaloPSA releases. If a label differs, look for the nearest equivalent in the same area of the portal.

Before you start

You need:

• A Conduit role that can manage connections — owner or admin on your organization.
• A HaloPSA login with the Administrator role — you need permission to create API applications under Configuration → Integrations.
• Your HaloPSA tenant name — the first part of your HaloPSA URL. If your URL is https://acmemsp.halopsa.com, your tenant is acmemsp.

Step 1 — Create a HaloPSA API application

1. Sign in to https://<your-tenant>.halopsa.com as an Administrator. Expected: the HaloPSA dashboard.
2. Open Configuration → Integrations → HaloPSA API, then View Applications. Expected: the applications list.
3. Click New. Expected: a new-application form.
4. Fill in:
   • Name — e.g. Conduit MCP Gateway, so the application’s purpose is clear when you audit the list later.
   • Grant Type — Client Credentials (the OAuth flow Conduit uses).
   • Permissions — grant only the scopes the AI needs. Common picks: read:tickets/edit:tickets for ticket workflows, read:clients for customer lookups, read:assets for asset queries, read:reports for report data.
5. Save. Expected: HaloPSA shows a Client ID and a Client Secret.

Caution

Copy both credentials now. The Client Secret is shown only once — if you lose it, you’ll need to regenerate it from the application’s detail page. Don’t paste either value into chat, email, or a shared document; the next step moves them directly into Conduit, which encrypts them at rest. If exposed, regenerate the Client Secret in HaloPSA first — the exposed value becomes useless immediately.

Step 2 — Connect HaloPSA in Conduit

1. In Conduit, go to Connections (/org/catalog). Expected: the vendor catalog.
2. Find HaloPSA in the catalog (under PSA) and click Connect. Expected: a credential form with three fields — Tenant, Client ID, Client Secret.
3. Fill in the tenant name from “Before you start,” and the Client ID and Client Secret from Step 1.
4. Click Connect. Expected: Conduit exchanges the credentials for an access token from HaloPSA’s /auth/token endpoint and shows a green Connected status. A bad credential pair or wrong tenant is rejected here, not on the first tool call.

The credential is stored at the organization scope, so every technician in your org shares this HaloPSA connection. Conduit refreshes the access token automatically as it expires — nothing further to renew.

Verify it worked

Connect an MCP client to Conduit — Claude Desktop, Claude Code, Cursor, or any MCP-compatible client (see Connecting an AI client) — and ask it to run a read-only HaloPSA tool, such as listing today’s tickets. You should get real data back, and the call appears in your audit log with the correct user, vendor (halopsa), and a successful status.

Troubleshooting

Symptom	Likely cause
Connect fails (“Invalid HaloPSA client credentials or tenant name”)	Most often a tenant-name typo — Conduit calls https://<tenant>.halopsa.com/auth/token, so a wrong tenant means the URL itself doesn’t resolve. Confirm the tenant is exactly the first part of your HaloPSA URL (lowercase, no .halopsa.com suffix). Also check the Client Secret wasn’t regenerated in HaloPSA after Conduit stored it, and that the application is Enabled.
Tool calls return 403 “no credentials for vendor”	HaloPSA isn’t connected at a scope this user can resolve. Connect it at the organization scope, or confirm the user’s team has credentials.
Tool calls succeed but specific actions are denied	The application’s OAuth scopes don’t cover that action — e.g. missing edit:tickets for a write call. Add the scope in HaloPSA (Configuration → Integrations → HaloPSA API → Applications → your app → Permissions); Conduit picks up the new permissions on the next token refresh, no re-entry needed.
Vendor health flips yellow briefly	HaloPSA tokens refresh on a rolling basis — a health check mid-refresh can show a brief yellow that clears within seconds. If it stays yellow more than 5 minutes, treat it as a credential issue above.
Need to rotate the Client Secret	Regenerate it in HaloPSA (Configuration → Integrations → HaloPSA API → Applications → your app → Regenerate Client Secret), then update the credential at /org/catalog. The Client ID and tenant stay the same.

Related

• Vendor connections — credential scopes, rotation, and the full vendor catalog.
• Security — how Conduit encrypts and resolves the credentials you just stored.