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

# Halo

> Connect Halo (HaloPSA) to Clarion so agents can search and create 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 and open new ones 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                                             |

<Note>
  `create_ticket` writes to Halo, so it requires human approval before it runs — you stay in control of when a ticket is actually created. Approval policies are managed in **Settings → Tools**.
</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**.