> ## 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.

# Freshservice

> Connect ThreatAware to Freshservice to sync IT service management and support data

## Overview

The Freshservice integration enables ThreatAware to connect with your Freshservice Support Portal, enabling visibility into IT service management, support tickets, and asset management. This integration helps correlate security findings with service management workflows.

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

## Data collected

The Freshservice integration provides:

* Company and department information
* Service management and ticket data
* Asset inventory information
* Support request and incident tracking

## Use cases

<CardGroup cols={2}>
  <Card title="IT Service Integration" icon="ticket">
    Sync security findings with IT service tickets and track remediation
  </Card>

  <Card title="Asset Management Correlation" icon="box">
    Correlate assets in ThreatAware with Freshservice asset records
  </Card>

  <Card title="Department Organisation" icon="building">
    Organise and track security findings by department or business unit
  </Card>

  <Card title="Compliance Tracking" icon="tasks">
    Link security compliance items to service management workflows
  </Card>
</CardGroup>

## Setup instructions

<Steps>
  <Step title="Log in to ThreatAware">
    Access the ThreatAware dashboard.

    * Navigate to **Settings** > **Systems**
    * Search for "Freshservice"
    * Click **Connect** to open the connection dialog
  </Step>

  <Step title="Obtain Freshservice Base URL">
    Log in to your Freshservice Support Portal with an administrator account.

    * Look at the URL in your browser address bar
    * The base URL is typically: `CompanyName.freshservice.com`
    * If you use a custom DNS name (e.g., `helpdesk.CompanyName.com`):
      * Use the original domain: `CompanyName.freshservice.com`
    * Copy your base URL for the next steps

    <Tip>
      If you're unsure of your base domain, check your Freshservice confirmation email or documentation.
    </Tip>
  </Step>

  <Step title="Access Profile Settings">
    While logged into Freshservice:

    * Click your **profile picture** in the top right corner
    * Select **Profile settings** from the dropdown menu
  </Step>

  <Step title="Generate API Key">
    In your Profile Settings:

    * Look for the **API Key** section on the right side of the page
    * You may need to complete a Captcha verification to view it
    * Copy the **API Key** displayed
    * Store it securely

    <Warning>
      Save your API Key immediately. Treat it as a sensitive credential.
    </Warning>
  </Step>

  <Step title="Retrieve Department ID">
    To find the Department ID:

    * Use the **Search Bar** in Freshservice
    * Type the name of the company/department you want to monitor
    * Ensure **Companies** is selected in the search filter
    * Navigate to the company's page
    * Look at the URL in your browser
    * The **Department ID** is displayed in the URL path
    * Copy the Department ID

    Example URL: `https://yourcompany.freshservice.com/companies/123456`
    The Department ID in this example is: `123456`
  </Step>

  <Step title="Input Details in ThreatAware">
    Return to the ThreatAware connection form and enter:

    * **Base URL**: The Freshservice domain (e.g., `companyname.freshservice.com`)
    * **API Key**: The key obtained from your profile settings
    * **Department ID**: The ID retrieved from the company page URL
    * Click **Connect** to establish the integration
  </Step>

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

    * Check that the **Integration Status** in ThreatAware shows as **Active**
    * Wait 5-10 minutes for initial data synchronization
    * Verify Freshservice company and department data appears in ThreatAware
  </Step>
</Steps>

## Required credentials

<AccordionGroup>
  <Accordion title="Base URL" icon="globe">
    **Field Name**: Freshservice Base URL
    **Type**: String
    **Description**: The domain URL for your Freshservice portal

    **Format**: `<companyname>.freshservice.com`
    **Example**: `acme.freshservice.com`
    **Note**: Do not include `https://` or trailing slashes

    If you use a custom domain, use the underlying Freshservice domain.
  </Accordion>

  <Accordion title="API Key" icon="key">
    **Field Name**: Freshservice API Key
    **Type**: String (sensitive)
    **Description**: The API key from your Freshservice profile settings

    <Tip>
      Store this key securely in your organisation's password manager. It provides access to your Freshservice data.
    </Tip>
  </Accordion>

  <Accordion title="Department ID" icon="building">
    **Field Name**: Freshservice Department ID
    **Type**: String
    **Description**: The ID for the company/department to monitor

    **Format**: Numeric identifier
    **Where to find**: Visible in the company page URL (e.g., `/companies/12345`)
    **Example**: `12345`

    <Tip>
      You can enter multiple Department IDs separated by commas if monitoring multiple departments.
    </Tip>
  </Accordion>
</AccordionGroup>

## Verification and testing

After setup, verify the integration is working correctly:

1. **Check Integration Status**
   * Navigate to **Settings** > **Systems** in ThreatAware
   * Confirm the Freshservice integration shows **Active** status
   * Check the last sync timestamp

2. **Verify Data Collection**
   * Wait 10 minutes for the initial data poll
   * Look for Freshservice company and department data appearing in ThreatAware
   * Verify the data matches your Freshservice portal

3. **Test Queries**
   * Create a test query to filter by department
   * Verify the results match your Freshservice data
   * Search for specific companies to confirm data accuracy

## Troubleshooting

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

    **Solutions**:

    * Verify the API Key is correctly copied without extra spaces
    * Ensure the key hasn't expired
    * Confirm you generated the key while logged in as an administrator
    * Try regenerating a new API Key from your profile settings
    * Check that your Freshservice account is active and not suspended
  </Accordion>

  <Accordion title="Incorrect Base URL" icon="ban">
    **Symptoms**: Cannot find or reach the Freshservice URL

    **Solutions**:

    * Verify the domain format: `companyname.freshservice.com`
    * Do not include `https://` protocol
    * Check for typos in the company name
    * If using a custom domain, use the underlying Freshservice domain
    * Test the URL in a browser with `https://` to verify it's accessible
  </Accordion>

  <Accordion title="Invalid Department ID" icon="database">
    **Symptoms**: Integration connects but no company data appears

    **Solutions**:

    * Verify the Department ID is correct
    * Navigate to the company page and check the URL for the correct ID
    * Ensure the company actually exists in Freshservice
    * Confirm the API key has permission to access the specified department
    * Try searching for the company name to find the correct ID
  </Accordion>

  <Accordion title="No Data Appearing" icon="server">
    **Symptoms**: Integration shows active but no data is visible

    **Solutions**:

    * Verify companies exist in your Freshservice instance
    * Wait at least 10 minutes for initial data synchronization
    * Confirm the Department ID is valid and corresponds to an existing company
    * Check that the API key has read permissions for companies
    * Review Freshservice API documentation for permission requirements
  </Accordion>
</AccordionGroup>

## Additional resources

<CardGroup cols={2}>
  <Card title="Freshservice Documentation" icon="book" href="https://freshservice.com">
    Official Freshservice documentation for API configuration
  </Card>

  <Card title="ThreatAware Support" icon="life-ring" href="mailto:help@threataware.com">
    Contact ThreatAware support for integration assistance
  </Card>
</CardGroup>

## Best practices

<Tip>
  **Credential Management**

  * Use an administrator account to generate the API Key
  * Store the API Key securely in your organisation's password manager
  * Rotate API keys annually or per your security policy
  * Document which accounts can generate API keys
  * Monitor for authentication failures in ThreatAware regularly
</Tip>

<Tip>
  **Integration Management**

  * Start by monitoring one department to test integration
  * Expand to additional departments once testing is successful
  * Regularly verify the Department IDs are still valid
  * Update Department IDs if company structure changes
  * Archive or remove integrations for departments no longer needed
</Tip>