> ## Documentation Index
> Fetch the complete documentation index at: https://docs.petrasecurity.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Halo PSA Integration
> Connect Petra with Halo PSA for automated ticketing and billing sync.
Click **Verify Permissions** on the Halo PSA integration page in Petra. It runs every permission check in one pass and tells you exactly what is missing.
## Ticketing
### Prerequisites
* Petra account
* Halo PSA administrator permissions
### 1. Create a Halo API user for Petra
1. In Halo PSA, navigate to `Configuration → Teams & Agents → Agents` and click **New**.
2. Fill in the following details and save:
* Username: `petra_api`
* Password: Use a strong password
* Use AD authentication: No
* Roles: Administrator (scope will be limited via API application permissions)
* Is an API-only Agent: Checked
* Default Team: No default team
* Work Hours: 24 Hours
* Can approve Purchase Orders: Unchecked
3. Update Agent Permissions (in the Permissions tab):
* Feature Access:
* Tickets Access Level: Read and Modify
* Customers Access Level: Read Only
* Ticket Permissions:
* Can add new Tickets: Yes
* Can view Unassigned Tickets: Yes
* Can view Tickets that are assigned to other Agents: Yes
4. Go to `Configuration → Integrations → HaloPSA API`.
5. Copy and store the values for **Tenant** and **Resource Server**.
6. Click **View Applications** → **New** and enter:
* Name: Petra
* Authentication Method: Client ID and Secret (Services)
* Login Type: Agent
* Agent to log in as: `petra_api`
### 2. Add an API Application for Petra
4. Copy the generated **Client ID** and **Client Secret** and store them safely, then click **Save**.
5. Open the **Permissions** tab and enable:
* Admin: webhooks
* Read: tickets
* Edit: tickets
* Read: customers
* Read: contracts
* Edit: contracts
* Read: items
* Edit: items
* Read: invoices
* Edit: invoices
Click **Save**.
### 3. Link Halo PSA in Petra
1. In Petra, open Settings: [https://app.petrasecurity.com/settings](https://app.petrasecurity.com/settings) and click **Link Halo PSA**.
2. Enter the credentials you saved earlier:
* Tenant
* Resource Server URL (omit the trailing `/api` if present)
* Client ID
* Client Secret
Then click **Save**. If authentication errors occur, correct the values and try again.
### Troubleshooting
Click **Verify Permissions** on the Halo PSA integration page in Petra. It runs every permission check in one pass and tells you exactly what is missing.
* **Authentication failed:** Verify Tenant, Resource Server (without `/api`), Client ID, and Client Secret. Regenerate credentials if needed.
* **Permission errors:** Confirm the API Application permissions are set as above and the `petra_api` Agent is active and API-only.
* **Ticket Type Category check failed:** Petra validates that the default Ticket Type in Halo can create tickets without a mandatory category field. If the permission check reports a category error, either set a default category on the ticket type in Halo admin, or make the category field non-mandatory on that ticket type.
* **Ticket routing unexpected:** Review Ticket Type settings and automations in Halo PSA.
Need help? Email us at [support@petrasecurity.com](mailto:support@petrasecurity.com).
***
## Delete Integration
Deleting a PSA integration is permanent. All associated data, including clients, ticket types, teams, service categories, statuses, priorities, and product mappings, will be removed and cannot be recovered.
Only **Admins** can delete a PSA integration. Full Members, Sales, and other roles do not have permission to perform this action.
To delete your Halo PSA integration:
1. Go to [Settings](https://app.petrasecurity.com/settings) and open your Halo PSA integration page.
2. Click **Delete Integration**.
3. Confirm the deletion in the dialog.
Once confirmed, Petra removes all Halo data from your organization, including synced clients, ticket types, teams, service categories, statuses, priorities, product item mappings, and tenant-to-client mappings. Billing sync stops immediately.
If you need to reconnect Halo PSA later, follow the setup steps in [Ticketing](#ticketing) above to link a new integration from scratch.
***
## Billing
Petra can sync billing data to Halo PSA by managing Software Licences. This section covers the additional setup required beyond the ticketing integration above.
### Additional Agent Permissions
Add the following to the `petra_api` agent permissions from [step 1](#1-create-a-halo-api-user-for-petra):
* **Feature Access:**
* Software Licencing Access Level: Read and Modify
* Products Access Level: Read Only
### Additional API Application Permissions
Add the following to the API Application permissions from [step 2](#2-add-an-api-application-for-petra):
* Read: softwarelicensing
* Edit: softwarelicensing
The existing `read:items` permission from the ticketing setup is also used by billing to map Petra products to Halo Items, so no changes are needed there.
### Configure Billing in Petra
Once the additional permissions are in place, go to [Settings](https://app.petrasecurity.com/settings) in Petra and configure billing sync for your Halo PSA tenants.
### Retrying a Single Tenant
If billing sync fails for one tenant, you do not need to re-run the full sync. Click the **Retry** button next to the failed tenant in the billing sync results table. Petra will re-compute that tenant's live billable count and sync only that tenant to Halo.
Need help? Email us at [support@petrasecurity.com](mailto:support@petrasecurity.com).