> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarion.cantina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Halo

> Connect Halo (HaloPSA) to Clarion so agents can search, create, update, close, and comment on Halo tickets during alert triage.

This guide walks you through connecting your Halo (HaloPSA / HaloITSM) instance to Clarion. Once connected, Clarion agents can call Halo's REST API on your behalf to look up existing tickets, open new ones, update and close them, and add comments as part of an investigation.

<Note>
  **Estimated time:** 5 minutes. You will need **Halo administrator** access to register an API application.
</Note>

## Prerequisites

* A **Halo** instance and administrator access to **Configuration → Integrations → Halo API**
* The ability to create a **Client Credentials** application in Halo
* A **Clarion workspace** with the Halo integration page open

***

## Step 1 — Register a Client Credentials application in Halo

1. Sign in to Halo as an administrator.
2. Go to **Configuration → Integrations → Halo API**.
3. Select **Authorise a new application**.
4. Choose **Client Credentials** as the authentication method.
5. Copy the generated **Client ID** and **Client Secret**.

<Warning>
  Copy the Client Secret immediately and store it securely — Halo may only show it once. Consider using a dedicated service application rather than one tied to a personal account.
</Warning>

6. On the application's **Permissions** tab, grant the permissions needed to read and create tickets (for example, the ticket read/write scopes, or `all`).
7. If you use a **hosted** Halo solution, note your **Tenant** identifier and your **Authorisation server URL** from the same **Halo API** page — you may need them in the next step.

***

## Step 2 — Enter credentials in Clarion

1. In Clarion, open **Integrations** and find **Halo (HaloPSA)** under Development & Planning.
2. Enter your **Halo URL** — your web-app base address, e.g. `https://acme.halopsa.com`. Clarion derives the REST API (`/api`) and authorisation server (`/auth`) from it.
3. Paste the **Client ID** and **Client Secret** from Halo.
4. **Hosted solutions only:** enter your **Tenant**, and an **Authorisation server URL** if it differs from your Halo URL.
5. Click **Connect**.

Clarion verifies the credentials by requesting an access token and making a lightweight ticket query before saving. If the credentials or URL are wrong, you'll see a clear error and nothing is persisted.

***

## What agents can do

Once connected, agents on this workspace gain access to the `/halo` action, which exposes these tools:

| Tool             | What it does                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| `search_tickets` | Search tickets, optionally filtered by a free-text query, open/closed state, client, or agent   |
| `get_ticket`     | Fetch a single ticket's details by its numeric ID                                               |
| `create_ticket`  | Open a new Halo ticket with a summary and details                                               |
| `update_ticket`  | Change an existing ticket's summary, details, status, priority, assigned agent, client, or type |
| `close_ticket`   | Move an existing ticket to a closed status                                                      |
| `add_comment`    | Add a note/action to an existing ticket (private by default, or visible to the end user)        |

<Note>
  `create_ticket`, `update_ticket`, `close_ticket`, and `add_comment` write to Halo, so they require human approval before they run — you stay in control of when a ticket is actually changed. `search_tickets` and `get_ticket` are read-only. Approval policies are managed in **Settings → Tools**.

  `add_comment` is retry-safe: if the ticket's most recent note is already identical, it returns that note instead of posting a duplicate.
</Note>

***

## Disconnect

To remove the integration:

1. In Clarion, open **Integrations → Halo (HaloPSA)**.
2. Click **Disconnect**.

This deletes the stored credentials. Agents on this workspace will no longer see the `/halo` action, and any saved skills that reference it will surface the integration as missing until you reconnect.

***

## Troubleshooting

### "Halo rejected the client credentials"

The Client ID or Secret is wrong, the application is not set to the **Client Credentials** method, or it lacks ticket permissions. Re-check the application in **Configuration → Integrations → Halo API**.

### "Halo returned 404"

The Halo URL is likely wrong. Use your web-app base URL (e.g. `https://acme.halopsa.com`), not the `/api` or `/auth` path. For hosted solutions, confirm your **Tenant** and **Authorisation server URL**.