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

# Configure Huntress Integration

> Connect Huntress to MSPortal.ai to sync Managed EDR agents, escalations, incident reports, and Managed SAT training data

This guide walks you through connecting Huntress to MSPortal.ai using the guided setup wizard. The Huntress integration is currently in Beta.

## Overview

Huntress provides Managed EDR (endpoint detection and response) and Managed Security Awareness Training (SAT) for MSPs. By integrating Huntress with MSPortal.ai, you can:

* Link Huntress agents to devices for endpoint security coverage tracking
* View escalations and incident reports on the Security page
* Include Huntress summary reports in client reporting
* Sync Managed SAT learners, training assignments, and phishing campaign results
* Track security awareness training progress per user and per company

## Prerequisites

* Active Huntress account with API access
* MSPortal.ai account with integration management permissions
* Huntress API key pair (public and private key)
* For Managed SAT: a Curricula OAuth client ID and secret

## Part 1: Generate Huntress API Keys

Before connecting to MSPortal.ai, create an API key pair in Huntress.

<Steps>
  <Step title="Log into Huntress">
    Access your Huntress dashboard at [huntress.io](https://huntress.io).
  </Step>

  <Step title="Open API Credentials">
    Click your account name in the top-right corner and select **API Credentials**.
  </Step>

  <Step title="Create API Key">
    Click **Setup** (or **Generate New API Key** if you have created keys before) and give the key a descriptive name such as `MSPortal Integration`.
  </Step>

  <Step title="Copy Both Keys">
    Huntress generates a **public key** and a **private key**. Copy both immediately.

    <Warning>
      **Store the private key securely!** Huntress only shows the private key once. If you lose it, you'll need to generate a new key pair.
    </Warning>
  </Step>
</Steps>

<Note>
  If you plan to sync Managed SAT training data, you will also need Curricula OAuth credentials (client ID and client secret). These are configured later in the wizard's Configure Sync step. Contact Huntress support if you don't have SAT API credentials for your account.
</Note>

***

## Part 2: MSPortal Setup Wizard

MSPortal.ai provides a guided 4-step wizard to connect and configure your Huntress integration:

1. **Connect** - Add API keys
2. **Configure Sync** - Choose data sets
3. **Map Organizations** - Link Huntress to companies
4. **Import Agents** - Create device coverage

### Starting the Wizard

<Steps>
  <Step title="Navigate to Integrations">
    In MSPortal.ai, go to **Settings > Integrations**.
  </Step>

  <Step title="Find Huntress">
    Locate the **Huntress** integration card in the list of available integrations.
  </Step>

  <Step title="Start Setup">
    Click **Configure** to launch the setup wizard.
  </Step>
</Steps>

***

### Step 1: Connect

Enter your Huntress API credentials to establish the connection.

<Steps>
  <Step title="Enter API Details">
    Fill in the connection fields:

    | Field               | Value                                                                                          |
    | ------------------- | ---------------------------------------------------------------------------------------------- |
    | **API URL**         | `https://api.huntress.io/v1` (pre-filled; only change this if Huntress support directs you to) |
    | **Public API key**  | The public key from Part 1                                                                     |
    | **Private API key** | The private key from Part 1                                                                    |

    <Note>
      Your API keys are stored securely using encrypted vault storage. They are never exposed in logs or API responses.
    </Note>
  </Step>

  <Step title="Test Connection">
    Click **Test Connection** to verify your credentials.

    A green "Connected to \[account name]" message appears when the test passes.

    If the connection fails:

    * Verify both keys were copied in full without extra spaces
    * Ensure the key pair has not been revoked in Huntress
    * Confirm the API URL is `https://api.huntress.io/v1`
  </Step>

  <Step title="Connect Huntress">
    Once the connection test passes, click **Connect Huntress** to save your credentials and proceed.
  </Step>
</Steps>

***

### Step 2: Configure Sync

Choose which Huntress datasets MSPortal syncs.

#### Managed EDR

Toggle the EDR datasets you want to sync:

| Option                               | Description                                             |
| ------------------------------------ | ------------------------------------------------------- |
| **Organizations**                    | Company mapping source for Huntress EDR data            |
| **Agents**                           | Device coverage source                                  |
| **Escalations and incident reports** | Security page source                                    |
| **Summary reports**                  | Reports page source                                     |
| **Auto-import mapped agents**        | Creates devices from mapped Huntress agents during sync |

<Tip>
  Leave **Auto-import mapped agents** off during initial setup. You can review and import agents manually in Step 4, then enable auto-import once you're confident in your organization mappings.
</Tip>

#### Managed SAT (Optional)

If you use Huntress Managed SAT, enable the **Managed SAT** toggle and enter your Curricula API credentials:

| Field                 | Value                                              |
| --------------------- | -------------------------------------------------- |
| **SAT API URL**       | `https://mycurricula.com/api/v1` (pre-filled)      |
| **SAT token URL**     | `https://mycurricula.com/oauth/token` (pre-filled) |
| **SAT client ID**     | Your Curricula OAuth client ID                     |
| **SAT client secret** | Your Curricula OAuth client secret                 |

Click **Test SAT Connection** to verify the credentials, then choose which SAT datasets to sync:

| Option              | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| **SAT accounts**    | Curricula account inventory used for SAT company mapping        |
| **SAT learners**    | User-level training status and learner profile data             |
| **SAT assignments** | Training assignments, assignment learners, and learner activity |
| **SAT phishing**    | Phishing campaigns and learner attempts                         |
| **SAT reports**     | Managed SAT account summary reports                             |

Click **Save Sync Settings** to continue.

***

### Step 3: Map Organizations

Map Huntress organizations to your MSPortal companies. This determines which data syncs to which company.

<Steps>
  <Step title="Sync Organizations">
    If no organizations appear, click **Sync** to fetch organizations from your Huntress account.

    <Info>
      The initial sync runs in the background. Check back after a few minutes if organizations don't appear immediately.
    </Info>
  </Step>

  <Step title="Use Quick Match">
    Click **Quick Match** to automatically match Huntress organizations to MSPortal companies based on name similarity. Review the results and adjust as needed.
  </Step>

  <Step title="Manual Mapping">
    For organizations that weren't automatically matched:

    1. Find the organization in the list
    2. Click the **Select company** dropdown in the "Mapped To" column
    3. Search for and select the correct MSPortal company

    To remove a mapping, click the **X** button next to the company badge.
  </Step>

  <Step title="Map SAT Accounts">
    If you enabled Managed SAT, a second mapping table appears for SAT accounts. Map each Curricula account to its MSPortal company the same way.
  </Step>

  <Step title="Proceed">
    Once your organizations are mapped, click **Next** to continue.

    <Warning>
      Only data from mapped organizations syncs to MSPortal. Unmapped organizations are skipped.
    </Warning>
  </Step>
</Steps>

***

### Step 4: Import Agents

Review synced data and link Huntress agents to devices.

<Steps>
  <Step title="Review Sync Stats">
    The Import step shows counts for each synced data type:

    * Organizations
    * Agents
    * Escalations
    * Incidents
    * Reports

    The "Last synced" timestamp shows when data was last updated.
  </Step>

  <Step title="Sync Huntress Data">
    Click **Sync Huntress Data** to trigger a full background sync of all enabled datasets. Depending on your data volume, this may take several minutes.
  </Step>

  <Step title="Import Agents as Devices">
    Click **Import Agents as Devices** to open the agent import page.

    Huntress agents link to existing MSPortal devices first. Only an agent that cannot be safely matched by Huntress identity, serial number, MAC address, or hostname in the mapped company creates a new device.

    The import page shows:

    | Status                      | Meaning                                      |
    | --------------------------- | -------------------------------------------- |
    | **Linked to devices**       | Agents already attached to a MSPortal device |
    | **Ready to link or create** | Agents that can be imported now              |
    | **Need company mapping**    | Agents whose organization isn't mapped yet   |
    | **Ignored**                 | Agents you've excluded from import           |

    Use **Import Selected** or **Import All Mapped** to link agents. Both link to existing devices first and only create new devices for unmatched agents.

    <Tip>
      Set up device type mappings before importing so brand-new devices get the right device type. The import page warns you if any Huntress types still need a mapping.
    </Tip>
  </Step>
</Steps>

***

## What Gets Synced

### Managed EDR

| Data Type            | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| **Organizations**    | Huntress organizations used for company mapping            |
| **Agents**           | Endpoint agents with hostname, OS, serial, and MAC details |
| **Escalations**      | Security escalations raised by Huntress analysts           |
| **Incident Reports** | Detailed incident reports for detected threats             |
| **Summary Reports**  | Periodic account and organization summary reports          |

### Managed SAT

| Data Type        | Description                                     |
| ---------------- | ----------------------------------------------- |
| **SAT Accounts** | Curricula accounts used for SAT company mapping |
| **Learners**     | User-level training status and learner profiles |
| **Assignments**  | Training assignments and per-learner activity   |
| **Phishing**     | Phishing campaigns and learner attempt results  |
| **SAT Reports**  | Managed SAT account summary reports             |

***

## Synchronization Schedule

After initial setup, all enabled datasets sync automatically once per day. You can trigger a manual sync at any time from the wizard's Import step using **Sync Huntress Data**.

<Note>
  Only datasets enabled in the Configure Sync step are synced. Data from unmapped organizations is skipped.
</Note>

***

## Managing Your Integration

After setup, manage your integration from **Settings > Integrations**:

| Action        | Description                                                |
| ------------- | ---------------------------------------------------------- |
| **Configure** | Re-open the wizard to modify settings or add more mappings |
| **Resync**    | Trigger a full data refresh                                |
| **Delete**    | Remove the integration                                     |

### Updating Your API Keys

<Steps>
  <Step title="Open Integration Settings">
    Go to **Settings > Integrations** and click **Configure** on the Huntress card.
  </Step>

  <Step title="Enter New Keys">
    On the Connect step, enter your new public and private keys.
  </Step>

  <Step title="Test and Save">
    Click **Test Connection**, then **Save Connection**.
  </Step>
</Steps>

### Adding More Organization Mappings

As you onboard new clients in Huntress:

<Steps>
  <Step title="Open the Map Step">
    Open the wizard and click **Map Organizations** in the stepper.
  </Step>

  <Step title="Sync and Map">
    Click **Sync** to fetch new organizations, then use Quick Match or manual mapping to connect them to companies.
  </Step>
</Steps>

***

## Troubleshooting

| Issue                       | Solution                                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Connection test fails       | Verify both API keys are correct and the key pair hasn't been revoked in Huntress                                                     |
| SAT connection test fails   | Confirm the client ID and secret are valid Curricula OAuth credentials                                                                |
| No organizations appear     | Click "Sync" on the Map Organizations step and wait a few minutes                                                                     |
| Agents not creating devices | Check that the agent's organization is mapped to a company and device type mappings are set                                           |
| Duplicate devices           | Agents link to existing devices by identity, serial, MAC, or hostname first; verify the existing device belongs to the mapped company |
| Data not syncing            | Ensure the dataset is enabled in Configure Sync and the organization is mapped                                                        |
| Stale data                  | Use "Sync Huntress Data" on the Import step to trigger a manual refresh                                                               |

***

## Security & Privacy

* **API Key Storage**: Your Huntress and Curricula credentials are encrypted using vault storage and never exposed in logs or responses
* **Data Isolation**: All synced data is tenant-isolated and only visible to your organization
* **Read-Only Access**: MSPortal only reads data from Huntress; it never modifies your Huntress configuration

***

## Next Steps

After setting up the Huntress integration:

<CardGroup cols={2}>
  <Card title="View Security Data" icon="shield-halved" href="/user-guides/security/index">
    Explore escalations and incident reports
  </Card>

  <Card title="Manage Devices" icon="laptop" href="/user-guides/devices/index">
    Review imported Huntress agents on the Devices page
  </Card>

  <Card title="Build Reports" icon="chart-bar" href="/user-guides/reporting/index">
    Include Huntress security data in client reports
  </Card>

  <Card title="Other Integrations" icon="plug" href="/user-guides/integrations/index">
    Explore additional integration options
  </Card>
</CardGroup>

## Need Help?

For assistance with the Huntress integration, contact [support@msportal.ai](mailto:support@msportal.ai).