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

# Halo Service Desk

> Connect ThreatAware to Halo Service Desk to sync ticket and asset data for IT service management

## Overview

The Halo Service Desk integration enables ThreatAware to collect read-only data from your Halo Service Desk environment, providing visibility into your IT service assets and ticket management data.

<Info>
  **Connection Method**: API
  **Setup Time**: 20 minutes
  **Access Required**: Administrator account
</Info>

## Data collected

The Halo Service Desk integration provides:

* Service desk tickets and issues
* Asset and device information
* Customer and organisation data
* Service configuration details

## Setup instructions

<Steps>
  <Step title="Access Halo Service Desk">
    Log in to your Halo Service Desk platform at `https://{tenantName}.haloservicedesk.com` with administrator credentials.
  </Step>

  <Step title="Create API User (Optional)">
    If you want a dedicated account for ThreatAware, create a new user:

    * Click **Customers** on the dashboard
    * Hover over **New** at the top-right and select **New User**
    * Enter username: **ThreatAware-API** (or your preferred name)
    * Select the site you want the user associated with
    * Scroll down and select **Service User** to exclude from user lists
    * Navigate to the **Permissions** tab and set **Asset Access Level** for the data you want ThreatAware to access
    * Click **Save**

    <Tip>
      If you prefer to use an existing admin user, you can skip this step and use that account instead.
    </Tip>
  </Step>

  <Step title="Navigate to API Settings">
    Configure API access in Halo Service Desk:

    * Click the **configuration button** at the bottom left of the navigation bar
    * In **All Features** > **Advanced Section**, click **Integrations**
    * Under **Featured Section**, select **Halo Service Desk API**
  </Step>

  <Step title="Create API Application">
    Generate API credentials:

    * Note the **Tenant** name (required for ThreatAware)
    * Click **View Applications**
    * Click the **New** button in the top right
    * Enter **Application Name**: `ThreatAware`
    * Select **Client ID and Secret (Services)**
    * Copy and securely store the **Client ID** and **Client Secret**

    <Warning>
      Keep your Client Secret secure. Treat it like a password and never share it in plain text.
    </Warning>
  </Step>

  <Step title="Set API Permissions">
    Configure permissions for the API application:

    * In the **Agent to log in as** dropdown, select the ThreatAware user (or an admin with required permissions)
    * Navigate to the **Permissions** tab
    * Select the **read:assets** permission
    * Click **Save**
  </Step>

  <Step title="Configure in ThreatAware">
    Complete the integration setup in ThreatAware:

    * Open ThreatAware and navigate to **Settings** > **Integrations**
    * Search for and select **Halo Service Desk**
    * Enter the required credentials:
      * **Tenant Name**: Your Halo Service Desk tenant name
      * **Client ID**: The Client ID generated above
      * **Client Secret**: The Client Secret generated above
    * Click **Save and Authorize** to establish the integration
  </Step>

  <Step title="Verify Connection">
    After connecting, verify the integration is working:

    * Check the **Integration Status** to confirm it shows **Active**
    * Wait for the initial data sync (typically within 1 hour)
    * Verify Halo Service Desk asset data appears in ThreatAware
  </Step>
</Steps>

## Required credentials

<AccordionGroup>
  <Accordion title="Tenant Name" icon="building">
    **Field Name**: Halo Service Desk Tenant Name
    **Type**: String
    **Description**: Your Halo Service Desk tenant identifier found in your instance URL

    **Format**: `{tenantName}` (from `https://{tenantName}.haloservicedesk.com`)
    **Example**: `acme-company`
  </Accordion>

  <Accordion title="Client ID" icon="key">
    **Field Name**: Halo Service Desk Client ID
    **Type**: String
    **Description**: The Client ID generated in Halo Service Desk API settings
  </Accordion>

  <Accordion title="Client Secret" icon="lock">
    **Field Name**: Halo Service Desk Client Secret
    **Type**: Password (encrypted)
    **Description**: The Client Secret associated with your Client ID

    <Tip>
      Store this credential securely in your organisation's password manager for future reference.
    </Tip>
  </Accordion>
</AccordionGroup>

## Verification and troubleshooting

<AccordionGroup>
  <Accordion title="Invalid Credentials" icon="triangle-exclamation">
    **Symptoms**: Integration status shows authentication failure

    **Solutions**:

    * Verify the **Client ID** and **Client Secret** are correct
    * Ensure credentials were copied without extra spaces
    * Confirm the **Tenant Name** matches your Halo instance
    * Check that the API application has not been deleted or disabled in Halo
  </Accordion>

  <Accordion title="Permission Denied" icon="ban">
    **Symptoms**: Integration connects but no data appears

    **Solutions**:

    * Verify the API application has the **read:assets** permission enabled
    * Check that the assigned user has appropriate asset access levels
    * Confirm the **Agent to log in as** user has access to the required assets
    * Review permissions in Halo Service Desk for the API user
  </Accordion>

  <Accordion title="Connection Timeout" icon="clock">
    **Symptoms**: Integration fails to connect or times out

    **Solutions**:

    * Verify the **Tenant Name** is correct and matches your instance URL
    * Check firewall rules allow outbound HTTPS (443) to haloservicedesk.com
    * Confirm the Halo Service Desk service is operational and accessible
    * Test your tenant URL in a browser to ensure it's reachable
  </Accordion>

  <Accordion title="No Data After 1 Hour" icon="database">
    **Symptoms**: Integration shows active but no service desk data appears

    **Solutions**:

    * Verify there is asset and ticket data in Halo Service Desk to collect
    * Check that the API user has appropriate asset access levels
    * Wait for the next sync cycle (typically hourly)
    * Review ThreatAware integration logs for detailed error messages
    * Contact Halo Service Desk support if issues persist
  </Accordion>
</AccordionGroup>

## Best practices

<Tip>
  **Credential Management**

  * Create a dedicated service account specifically for ThreatAware integration
  * Document credentials securely in your organisation's password manager
  * Rotate API credentials annually or per your security policy
  * Monitor for authentication failures in ThreatAware regularly
  * Disable the API application immediately if credentials are compromised
</Tip>

<Tip>
  **Security Considerations**

  * Only grant minimum necessary permissions (read:assets)
  * Use a dedicated service user rather than a personal admin account
  * Review API access logs in Halo Service Desk periodically
  * Follow your organisation's least privilege principles
</Tip>