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

> Connect your Hudu instance to MSPortal.ai to sync documentation, assets, passwords, and procedures

This guide walks you through connecting your Hudu instance to MSPortal.ai using our streamlined 5-step setup wizard.

## Overview

Hudu is an IT documentation platform that helps MSPs organize knowledge bases, asset information, passwords, and procedures. By integrating Hudu with MSPortal.ai, you can:

* Access Hudu documentation, articles, and procedures directly from MSPortal
* Browse and reveal passwords securely without leaving MSPortal
* Map Hudu companies to your MSPortal companies for unified data access
* Push compliance data from MSPortal to Hudu Magic Dash

## Prerequisites

Before you begin, ensure you have:

* Active Hudu account with administrative access
* MSPortal.ai account with integration management permissions
* Companies already set up in MSPortal (from your PSA integration or manually created)

<Warning>
  Only one documentation integration can be active at a time. If you already have IT Glue connected, you must remove it before setting up Hudu. Go to **Settings > Integrations**, open the IT Glue integration, and delete it first.
</Warning>

<Note>
  The Hudu integration maps companies to existing companies in MSPortal. Import your companies from your PSA integration first, or create them manually before setting up Hudu.
</Note>

***

## Part 1: Generate API Credentials in Hudu

Before connecting to MSPortal, you need to create an API key in your Hudu instance.

<Steps>
  <Step title="Log into Hudu">
    Access your Hudu instance at your organization's URL (e.g., `https://your-instance.huducloud.com`).
  </Step>

  <Step title="Navigate to API Keys">
    Go to **Admin > API Keys** from the main navigation. Depending on your Hudu version, this may also be under **Account Settings > API Keys**.
  </Step>

  <Step title="Create a New API Key">
    Click **New API Key** and enter a descriptive name such as `MSPortal Integration`.

    <Tip>
      Use a descriptive name so you can easily identify this key's purpose later. Avoid generic names like "API Key 1".
    </Tip>
  </Step>

  <Step title="Copy the API Key">
    After creating the key, copy it immediately and store it in a secure location.

    <Warning>
      **Copy the API key now!** It will not be displayed again after you leave this page. If you lose the key, you will need to generate a new one.
    </Warning>
  </Step>

  <Step title="Note Your Instance URL">
    Make note of your full Hudu instance URL. This is the URL you use to access Hudu in your browser, for example:

    | Format          | Example                              |
    | --------------- | ------------------------------------ |
    | **Hudu Cloud**  | `https://your-company.huducloud.com` |
    | **Self-Hosted** | `https://hudu.yourcompany.com`       |
  </Step>
</Steps>

### Required Information

Before proceeding to MSPortal, ensure you have:

| Information       | Description                                                               |
| ----------------- | ------------------------------------------------------------------------- |
| **Hudu Base URL** | Your full Hudu instance URL (e.g., `https://your-instance.huducloud.com`) |
| **API Key**       | The API key you just generated                                            |

***

## Part 2: MSPortal Setup Wizard

MSPortal provides a guided 5-step wizard to connect and configure your Hudu integration. Steps 3 through 5 are optional and can be configured later.

### Starting the Wizard

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

  <Step title="Start Setup">
    Find the **Hudu** integration card and click **Setup** (or **Configure** if previously connected) to launch the setup wizard.
  </Step>
</Steps>

***

### Step 1: Connect

Enter your Hudu credentials to establish the connection.

<Steps>
  <Step title="Enter Your Hudu Base URL">
    Enter the full URL of your Hudu instance in the **Hudu Base URL** field.

    | Field             | Example                               |
    | ----------------- | ------------------------------------- |
    | **Hudu Base URL** | `https://your-instance.huducloud.com` |

    <Note>
      Include `https://` at the beginning. Do not include a trailing slash.
    </Note>
  </Step>

  <Step title="Enter Your API Key">
    Paste your Hudu API key into the **API Key** field.
  </Step>

  <Step title="Test Connection">
    Click **Test Connection** to verify your credentials. You will see a green "Connection tested successfully" message when the test passes.

    If the connection fails:

    * Verify your Hudu Base URL is correct and includes `https://`
    * Check that your API key is copied exactly, with no extra spaces
    * Ensure your Hudu account has API access enabled
    * Confirm your Hudu instance is accessible from the internet (self-hosted instances behind a firewall may need configuration)
  </Step>

  <Step title="Create Integration">
    Once the connection test passes, click **Create Integration** to save your credentials and proceed.

    <Info>
      Your API key is stored securely using encrypted vault storage. It is never exposed in logs or API responses.
    </Info>
  </Step>
</Steps>

***

### Step 2: Map Companies (Required)

Map your Hudu companies to MSPortal companies. This determines which documentation, assets, and passwords are accessible for each company.

<Steps>
  <Step title="Wait for Initial Sync">
    After creating the integration, MSPortal fetches your companies from Hudu. This may take a few moments depending on the number of companies in your account.
  </Step>

  <Step title="Use Quick Match (Recommended)">
    Click **Quick Match** to automatically match Hudu companies to MSPortal companies. Quick Match uses two methods to find matches:

    1. **ID Number matching** -- If your Hudu companies have an `id_number` field that matches a PSA external company ID already imported into MSPortal, these are matched first
    2. **Case-insensitive name matching** -- Companies with matching names (ignoring case and whitespace) in both systems are matched automatically

    Review the results and adjust any incorrect mappings.

    <Tip>
      Quick Match saves significant time when you have many companies. Start with Quick Match, then manually map any remaining companies.
    </Tip>
  </Step>

  <Step title="Manually Map Remaining Companies">
    For companies that were not automatically matched:

    1. Find the Hudu company in the list
    2. Click the company dropdown in the "Mapped To" column
    3. Search for and select the correct MSPortal company
    4. The mapping is saved automatically
  </Step>

  <Step title="Unmap Companies (Optional)">
    To remove a mapping, click the **X** button next to the mapped company name.
  </Step>

  <Step title="Filter the List">
    Use the filter dropdown to show:

    * **All** -- View all Hudu companies
    * **Mapped** -- View only companies with MSPortal mappings
    * **Unmapped** -- View companies that still need mapping
  </Step>

  <Step title="Proceed">
    Once you have mapped at least one company, click **Next** to continue.
  </Step>
</Steps>

<Warning>
  You must map at least one company before proceeding. Only documentation, assets, and passwords from mapped companies will be accessible in MSPortal.
</Warning>

***

### Step 3: Documentation (Optional)

Configure which types of Hudu documentation to sync into MSPortal.

<Steps>
  <Step title="Review Available Content Types">
    The Documentation step displays the types of content available for sync:

    | Content Type   | Description                               |
    | -------------- | ----------------------------------------- |
    | **Articles**   | Knowledge base articles and documentation |
    | **Assets**     | IT asset information organized by layout  |
    | **Procedures** | Documented processes and runbooks         |

    <Note>
      Password sharing is configured separately in Step 4. This step does not affect password visibility.
    </Note>
  </Step>

  <Step title="Review Asset Layouts">
    MSPortal fetches your available asset layouts from Hudu in real time. Each layout represents a category of assets (e.g., "Network Devices", "Software Licenses", "Cloud Services").

    Toggle individual asset layouts on or off to control which asset types are synced.
  </Step>

  <Step title="Configure Sync Preferences">
    Enable or disable each content type based on what you want accessible in MSPortal. You can adjust these settings at any time by returning to the wizard.
  </Step>

  <Step title="Proceed">
    Click **Next** to continue to password sharing configuration, or skip ahead if you do not need to configure passwords.
  </Step>
</Steps>

<Note>
  This step is optional. If you skip it, no documentation will be synced. You can return to configure documentation sync at any time.
</Note>

***

### Step 4: Password Sharing (Optional)

Configure how passwords from Hudu are shared within MSPortal. This step allows you to control password visibility on a per-company basis.

<Steps>
  <Step title="Understand Password Security">
    Before configuring password sharing, be aware of how MSPortal handles Hudu passwords:

    * **Passwords are never stored in MSPortal.** Every time a user reveals a password, it is fetched live from Hudu at that moment.
    * **Every password reveal is audit-logged.** MSPortal records which user viewed which password and when.
    * **Access requires permissions.** Users must have the `read_documentation_passwords` permission to reveal passwords.
  </Step>

  <Step title="Enable Password Sharing">
    Toggle password sharing **on** to allow team members with the appropriate permission to reveal passwords from Hudu within MSPortal.

    When enabled, users with the `read_documentation_passwords` permission can browse and reveal passwords for mapped companies.
  </Step>

  <Step title="Configure Per-Company Settings (Later)">
    After completing the wizard, per-company password folder visibility and role-based access can be fine-tuned in **Settings > Documentation > Passwords**.

    <Tip>
      Use folder-level sharing to restrict access to sensitive credentials. For example, you might share a "General Access" folder while keeping "Domain Admin" passwords restricted.
    </Tip>
  </Step>

  <Step title="Proceed">
    Click **Next** to continue to Magic Dash configuration.
  </Step>
</Steps>

<Warning>
  Password sharing gives MSPortal users access to credentials stored in Hudu. Ensure only appropriate users have the `read_documentation_passwords` permission in MSPortal. Fine-tune per-company folder access in **Settings > Documentation > Passwords** after setup.
</Warning>

***

### Step 5: Magic Dash (Optional)

Push compliance data from MSPortal into Hudu Magic Dash to surface compliance status directly in your Hudu interface.

<Steps>
  <Step title="Understand Magic Dash">
    Hudu Magic Dash allows external tools to push summary data into company dashboards. When enabled, MSPortal pushes compliance status, security metrics, and device health data into Hudu so your team can see this information without leaving Hudu.
  </Step>

  <Step title="Enable Magic Dash">
    Toggle Magic Dash **on** to push compliance and device health data to Hudu Magic Dash for each mapped company. Data updates automatically on a regular schedule.
  </Step>

  <Step title="Complete Setup">
    Click **Complete Setup** to finish the wizard. Your Hudu integration is now active.
  </Step>
</Steps>

<Note>
  Magic Dash is the only part of the Hudu integration where data flows from MSPortal to Hudu. All other data flows from Hudu into MSPortal.
</Note>

***

## What Gets Synced

| Data Type       | Direction       | Description                                        |
| --------------- | --------------- | -------------------------------------------------- |
| Companies       | Hudu → MSPortal | Company records for mapping purposes               |
| Articles        | Hudu → MSPortal | Knowledge base articles and documentation          |
| Asset Layouts   | Hudu → MSPortal | Asset type definitions and their associated assets |
| Passwords       | Hudu → MSPortal | Live-fetched on reveal (never stored in MSPortal)  |
| Procedures      | Hudu → MSPortal | Process documentation and runbooks                 |
| Compliance Data | MSPortal → Hudu | Compliance check results pushed to Magic Dash      |

<Info>
  Passwords are unique in that they are never stored or cached in MSPortal. Each time a user reveals a password, it is fetched in real time from the Hudu API. This ensures passwords are always current and reduces the security risk of storing credentials in a second system.
</Info>

***

## Managing Your Integration

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

| Action        | Description                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| **Configure** | Re-open the setup wizard to modify settings, adjust company mappings, or change documentation sync preferences |
| **Resync**    | Trigger a manual sync to refresh data from Hudu                                                                |
| **Delete**    | Remove the integration, including all company mappings and stored credentials                                  |

### Re-running the Wizard

You can return to any step of the setup wizard at any time:

1. Go to **Settings > Integrations**
2. Click **Configure** on the Hudu card
3. Navigate between steps using the step indicators or Back/Next buttons

### Adding New Company Mappings

As you onboard new clients in Hudu:

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

  <Step title="Navigate to Map Step">
    Click on Step 2 (Map Companies) in the wizard stepper.
  </Step>

  <Step title="Map New Companies">
    New Hudu companies will appear in the list. Use Quick Match or manual mapping to connect them to MSPortal companies.
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection test fails">
    **Causes:**

    * Incorrect Hudu Base URL or API key
    * Hudu instance is not reachable from the internet
    * API key has been revoked or expired
    * Self-hosted Hudu behind a firewall

    **Solutions:**

    1. Verify your Hudu Base URL includes `https://` and matches your browser URL exactly
    2. Check that the API key is copied correctly with no extra spaces
    3. For self-hosted instances, ensure your Hudu server allows incoming API requests
    4. Generate a new API key in Hudu if the current one may be invalid
  </Accordion>

  <Accordion title="No companies appear in the mapping step">
    **Causes:**

    * Initial sync still in progress
    * API key lacks read permissions for companies

    **Solutions:**

    1. Wait a few minutes for the initial company sync to complete
    2. Verify your API key has read access to companies in Hudu
    3. Check that your Hudu instance has at least one company configured
  </Accordion>

  <Accordion title="Quick Match did not map all companies">
    **Causes:**

    * Company names differ between Hudu and MSPortal
    * Hudu companies do not have `id_number` values set

    **Solutions:**

    1. Use manual mapping for companies with different names
    2. Add `id_number` values to Hudu companies if you want ID-based matching
    3. Ensure company names are consistent across both platforms where possible
  </Accordion>

  <Accordion title="Passwords are not accessible">
    **Causes:**

    * Password sharing not configured for the company
    * User lacks the `read_documentation_passwords` permission
    * Specific folders selected but the password is in a different folder

    **Solutions:**

    1. Return to Step 4 (Password Sharing) in the wizard and verify the company has password sharing enabled
    2. Check that the user has the `read_documentation_passwords` permission under **Settings > Users and Roles**
    3. If using folder-level sharing, verify the correct folders are selected
  </Accordion>

  <Accordion title="Documentation or articles not appearing">
    **Causes:**

    * Documentation sync not enabled in Step 3
    * Content type (articles, assets, procedures) is toggled off
    * Company is not mapped

    **Solutions:**

    1. Return to Step 3 (Documentation) and enable the desired content types
    2. Verify the relevant asset layouts are toggled on
    3. Confirm the company is mapped in Step 2
  </Accordion>

  <Accordion title="Compliance data not showing in Hudu Magic Dash">
    **Causes:**

    * Magic Dash not enabled in Step 5
    * Company mapping incomplete

    **Solutions:**

    1. Return to Step 5 (Magic Dash) and enable the feature
    2. Verify the company is mapped in Step 2
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Map Companies First" icon="building">
    Complete company mapping before configuring documentation, passwords, or Magic Dash. All other features depend on accurate company mappings.
  </Card>

  <Card title="Use Quick Match" icon="wand-magic-sparkles">
    Start with Quick Match for company mapping, then manually adjust any incorrect matches. It saves significant time for large environments.
  </Card>

  <Card title="Restrict Password Access" icon="lock">
    Use folder-level password sharing to limit which credentials are accessible. Only grant the `read_documentation_passwords` permission to users who need it.
  </Card>

  <Card title="Audit Password Access" icon="clipboard-list">
    Regularly review the audit log to monitor which users are accessing passwords. This helps maintain accountability and detect unusual access patterns.
  </Card>

  <Card title="Keep Names Consistent" icon="arrows-rotate">
    Maintaining consistent company names between Hudu and your PSA makes Quick Match more effective and reduces manual mapping effort.
  </Card>
</CardGroup>

***

## Related Resources

* [Import Companies](/user-guides/integrations/import-companies) - General company import guide
* [Clear and Resync Integrations](/user-guides/integrations/clear-and-resync-integrations) - Troubleshooting sync issues
* [Users and Roles](/user-guides/settings/users-roles) - Managing permissions including password access
* [Integrations Overview](/user-guides/integrations/index) - Browse all available integrations