> ## 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 CyberHoot Integration

> Connect CyberHoot to MSPortal.ai to sync security awareness, compliance, HootScore, and HootPhish metrics

This guide walks you through connecting CyberHoot to MSPortal.ai using the guided setup wizard.

<Note>
  The CyberHoot integration is currently available in beta. Contact [support@msportal.ai](mailto:support@msportal.ai) if CyberHoot does not appear in your available integrations.
</Note>

## Overview

CyberHoot is a security awareness training and phishing simulation platform for MSPs. By integrating CyberHoot with MSPortal.ai, you can:

* View security awareness and compliance metrics for every client in one place
* Track HootScore and per-user training compliance
* Monitor HootPhish challenges and per-participant results
* Include security awareness metrics in client reports

## Prerequisites

* An active CyberHoot partner account
* Your CyberHoot API URL and API key
* MSPortal.ai account with integration management permissions

<Info>
  The CyberHoot API exposes endpoints based on the Power-Ups enabled for your account. MSPortal detects the available features automatically during connection, so you only see data your CyberHoot plan provides.
</Info>

## Part 1: Get Your CyberHoot API Credentials

Before connecting to MSPortal.ai, you need your API URL and API key from CyberHoot.

<Steps>
  <Step title="Log into CyberHoot">
    Sign in to your CyberHoot Partner portal with an administrator account.
  </Step>

  <Step title="Locate Your API Key">
    Open your partner settings and find the API key section. Copy the API key, or generate one if none exists.

    <Warning>
      **Store the API key securely!** Regenerating the key invalidates the previous one, so any other tools using the old key would stop working.
    </Warning>
  </Step>

  <Step title="Note Your API URL">
    Your API URL is based on your CyberHoot deployment and always ends with `/api`, for example:

    ```
    https://autopilot.cyberhoot.com/api
    ```

    The URL must use HTTPS on the standard port.
  </Step>
</Steps>

***

## Part 2: MSPortal Setup Wizard

MSPortal.ai provides a guided 3-step wizard to connect and configure your CyberHoot integration.

### Starting the Wizard

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

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

    <Note>
      If the CyberHoot card is not visible, contact [support@msportal.ai](mailto:support@msportal.ai) to have it enabled for your account.
    </Note>
  </Step>

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

***

### Step 1: Connect

Enter your CyberHoot credentials to establish the connection. As the wizard notes: copy the API URL and API key from the CyberHoot Partner portal. Customer discovery and available features are detected automatically.

<Steps>
  <Step title="Enter Credentials">
    Fill in the two fields:

    | Field       | Value                                                              |
    | ----------- | ------------------------------------------------------------------ |
    | **API URL** | Your CyberHoot API URL, e.g. `https://autopilot.cyberhoot.com/api` |
    | **API key** | The API key from your CyberHoot Partner portal                     |

    <Note>
      Your API key is stored securely using Supabase Vault encryption. It is never exposed in logs or API responses.
    </Note>
  </Step>

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

    On success, you'll see a confirmation showing your partner name and how many customers were found, for example "Connection verified for Acme MSP with 25 customers."

    If the connection fails:

    * Verify the API URL uses HTTPS and ends with `/api`
    * Verify the API key was copied without extra spaces
    * Ensure the key has not been regenerated since you copied it
  </Step>

  <Step title="Connect">
    Once the connection test passes, click **Connect** to save your credentials and create the integration. MSPortal immediately starts discovering your CyberHoot customers in the background.

    When editing an existing integration, the button is labeled **Save connection**.
  </Step>
</Steps>

***

### Step 2: Map Companies

Map CyberHoot customers to your MSPortal companies. This determines which data syncs to which company.

<Steps>
  <Step title="Wait for Customer Discovery">
    Customer discovery starts automatically when you connect. If no customers appear yet, wait a moment and check again.

    The list includes each customer's **Domain** where CyberHoot provides one.
  </Step>

  <Step title="Use Quick Match">
    Click **Quick Match** to automatically match CyberHoot customers to MSPortal companies based on name similarity. Review the suggested matches and apply the ones that look correct.
  </Step>

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

    1. Find the customer 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, use the unmap button next to the company badge.
  </Step>

  <Step title="Create New Companies">
    If a CyberHoot customer doesn't have a corresponding MSPortal company, use **Create new company** to add one. New companies are automatically mapped to their CyberHoot counterparts.
  </Step>

  <Step title="Import Selected">
    Pending mappings show a **Pending** badge. Click **Import Selected** to save them, or click **Next**, which saves pending mappings automatically.

    <Warning>
      You must map at least one customer before proceeding. Only data from mapped customers is synced to MSPortal.
    </Warning>

    Saving mappings automatically triggers a detailed sync of the newly mapped customers.
  </Step>
</Steps>

***

### Step 3: Status

Review the sync status and finish setup.

<Steps>
  <Step title="Review Sync Stats">
    The Status step displays:

    * **Mapped customers** (mapped out of total discovered)
    * **Active users**
    * **Mean HootScore**
    * **HootPhish challenges**

    The "Last synced" timestamp shows when data was last updated. Metrics that your CyberHoot plan does not provide display as "Not provided".
  </Step>

  <Step title="Explore Your Data">
    Use the **View security awareness** and **View reports** buttons to jump directly to the synced data.
  </Step>

  <Step title="Complete Setup">
    Click **Complete Setup** to finish the wizard and return to the Integrations page.
  </Step>
</Steps>

***

## What Gets Synced

CyberHoot integration syncs the following data types to MSPortal for mapped customers:

### Customers

Your CyberHoot customer inventory, including customer name and domain, used for mapping and for customer-level metrics such as active user counts and HootScore.

### Users

Per-user records for each mapped customer, including training compliance and user ranking data.

### Compliance Snapshots

Daily snapshots of customer-level compliance metrics, including HootScore and active user counts, so you can track security awareness trends over time.

### HootPhish Challenges

Phishing challenge records for each mapped customer, including per-participant results linked to synced users where an email match exists.

<Info>
  Available data depends on the Power-Ups enabled in your CyberHoot account. MSPortal detects the available capabilities per customer and syncs what your plan provides.
</Info>

***

## Synchronization Schedule

After initial setup, data syncs automatically:

| Data Type                | Sync Frequency    |
| ------------------------ | ----------------- |
| All mapped customer data | Daily (07:05 UTC) |

In addition to the daily schedule:

* Connecting or updating credentials triggers a customer discovery sync
* Saving customer mappings triggers a detailed sync of the newly mapped customers

***

## Managing Your Integration

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

| Action        | Description                                                   |
| ------------- | ------------------------------------------------------------- |
| **Configure** | Re-open the wizard to update credentials or customer mappings |
| **Delete**    | Remove the integration (available in the wizard footer)       |

### Updating Your API Key

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

  <Step title="Enter New Credentials">
    On the Connect step, update the API URL or API key.
  </Step>

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

### Deleting the Integration

Click **Delete** in the wizard footer. This removes the integration, synced CyberHoot data, and stored credentials for the connection.

***

## Troubleshooting

| Issue                        | Solution                                                                                       |
| ---------------------------- | ---------------------------------------------------------------------------------------------- |
| CyberHoot card not visible   | Contact [support@msportal.ai](mailto:support@msportal.ai) to enable CyberHoot for your account |
| Connection test fails        | Verify the API URL ends with `/api`, uses HTTPS, and the API key is current                    |
| No customers in the Map step | Customer discovery runs after connecting; wait a minute and check again                        |
| Data not syncing             | Ensure customers are mapped to companies; only mapped customer data syncs                      |
| Metrics show "Not provided"  | The corresponding CyberHoot Power-Up is not enabled for that customer                          |
| Stale data                   | Data refreshes daily at 07:05 UTC; re-saving a mapping triggers a fresh sync for that customer |

***

## Security & Privacy

* **API Key Storage**: Your CyberHoot API key is encrypted using Supabase Vault 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 CyberHoot data; it never modifies your CyberHoot configuration

***

## Next Steps

After setting up the CyberHoot integration:

<CardGroup cols={2}>
  <Card title="Build Reports" icon="chart-bar" href="/user-guides/reporting/index">
    Include security awareness metrics in client reports
  </Card>

  <Card title="Sync Schedules" icon="clock" href="/user-guides/integrations/sync-schedules">
    See when each integration refreshes its data
  </Card>

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

  <Card title="Integration FAQ" icon="circle-question" href="/user-guides/integrations/faq">
    Answers to common integration questions
  </Card>
</CardGroup>

## Need Help?

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