Domotz Ubiquiti UniFi Integration
If you have a Local controller or a Cloud controller (e.g. Ubiquiti Cloud, or a third-party cloud controller like Hostifi), you can unlock advanced features inside Domotz.
Specifically, you can remotely monitor your UniFi devices, including network switches, WiFi controllers, and access points, get device status alerts, and access enhanced network management features for certain UniFi devices.
Introduction
To integrate Domotz with your Ubiquiti UniFi Controller and monitor controlled devices such as managed switches and wireless access points, you’ll need to connect using one of the following three methods:
- Cloud API Key (recommended)
- Username and Password:
- Cloud Username and Password with 2FA
- Local Username and password
Controller Type Compatibility
Not all connection methods are available on every controller type. Use this table to check which methods your setup supports before proceeding.
| Controller Type | Local Username & Password | Cloud Username & Password (+2FA) | Cloud API Key |
|---|---|---|---|
| Self-hosted UniFi Network Server (legacy) | ✅ | ✅ (if remote-access enabled) | ❌ (not supported) |
| Self-hosted UniFi OS Server | ✅ | ✅ (if remote-access enabled) | ✅ (if remote-access enabled) |
| CloudKey (Gen1, Gen2, Gen2 Plus, CloudKey+, CloudKey Enterprise) | ✅ | ✅ | ✅ |
| Cloud Gateway (Dream Machine, UCG-Ultra, UCG-Max, etc.) | ✅ | ✅ | ✅ |
| Official UniFi Hosting | ❌ | ✅ | ✅ |
| Third-party hosting (e.g. HostiFi) | ❌ | ✅ | ✅ |
Notes: “if remote-access enabled” means the self-hosted controller must be connected to a UI.com account with remote access enabled for cloud-based methods to work. To check it: on the legacy UniFi Network Server, go to Settings > System > Advanced and toggle Remote Management; on UniFi OS Server (and other UniFi OS consoles), go to OS Settings > Console and toggle Remote Access. The legacy UniFi Network Server does not support API key authentication — only UniFi OS consoles and UniFi OS Server support API keys.
Where supported, we recommend integrating via API Key rather than the other methods available. The API Key method provides richer uplink and downstream link data, giving more accurate topology mapping between the router and connected switches/APs.
1. Cloud API Key Method
1.1 Creating the API Key
To create the API Key on your UniFi Cloud navigate to https://unifi.ui.com and login with your UniFi username and password.
- Access the Site Manager Settings section.
- Follow to the sub-section called API Keys
- Click on Create New API Key
Creating a New API Key in UniFi Settings
1. Access the UniFi Settings by selecting the gear icon on the left sidebar.
2. In the navigation menu, choose "API Keys" under the "Network" section.
3. Click on "Create New API Key" in the main window to initiate the creation of a new API key.
You can also specify the API Scope by selecting relevant checkboxes like "Site Manager," "Network," or others, and choose applicable sites such as "Brasil - UDM" or "Home - UDM Pro". Adjust settings like "Created By" and "Last Used" as needed.
On the new API Key configure the following:
Creating a New API Key.
1. Enter a name for the API key in the "Name" field, such as "Domotz API Key."
2. Select the expiration duration from the "Expiration" dropdown; the default is "Never Expires."
3. Enable or disable features under the "Applications" section by checking or unchecking options like "Site Manager" and "UniFi Applications."
4. Choose the relevant application by selecting, such as "Network."
5. Select the applicable site from the "Sites" section, like "Home - UDM Pro."
6. Click the "Create" button to finalize the creation of the API key, or select "Cancel" to abort the process.
- Name: Choose any name you’d like.
- Expiration: Set it to never expire.
- Permissions: Check the boxes for Site Manager and UniFi Applications.
- Application: Select Network as the application we need access to, and remove the others.
- Sites: Grant access to at least one site you want to connect via the UniFi integration. If you select All Sites, you’ll be able to reuse the same API key across multiple Domotz Collectors.
Click on Create and copy the API Key. You will not have another opportunity to do it.
API Key Creation Confirmation
1. The message confirms that an API key has been successfully created.
2. Instructions advise that the key is shown only once for security purposes. It is essential to copy the key immediately and store it securely.
3. The key itself is displayed in a text box labeled "Key."
4. A blue "Copy Key" button is provided to easily copy the key to your clipboard.
1.2 Adding the API Key to Domotz
Navigate to the Domotz Webapp > Collectors > Select the collector with your UniFi network > Devices section > at the Device Configuration options click on Cloud and Local Integrations:
Accessing Cloud and Local Integrations in Device Configuration Menu
1. Navigate to the main menu and click on "Devices" to access device-related settings.
2. Expand the "Device Configuration" section on the left sidebar.
3. Select "Cloud and Local Integrations" from the list of options.
4. Use this section to manage integrations specific to your devices within the network.
In the right pane, you can view network equipment status, including total and online counts. Use the filters and selection options to organize or manage your devices effectively.
On the new screen, click on Add Controller at the Ubiquiti Unifi Controller
Steps to Add a Controller in Cloud and Local Integrations
1. Navigate to the "Cloud and Local Integrations" section in the Explorer panel.
2. Locate the "Available Cloud and Local Integrations" heading.
3. Under "Ubiquiti Unifi Controller," read the description explaining the enhanced features and capabilities.
4. Click the "Add Controller" button to initiate adding a new controller. This will enhance the Domotz User Interface with features from the Ubiquiti Unifi Controller.
Select Connect via API Key
Connecting to the Ubiquiti Unifi Controller Service.
1. Select your connection method:
- Choose "Connect via Username & Password" to use your UniFi credentials.
- Choose "Connect via API Key" to connect with a Site Manager API key. This option is currently selected.
2. Click "Next" to proceed with your chosen method or "Cancel" to exit.
Paste your API Key and click on Connect
Connect to the Ubiquiti Unifi Controller Service
1. Enter a Site Manager API key in the "API Key" field to connect your Ubiquiti Unifi Controller devices via the cloud.
2. If you need assistance generating a Site Manager API key, follow the "Learn how here" link to access instructions.
3. Once the API key is entered, click the "Connect" button to proceed.
4. Use the "Back" button if you need to return to the previous page.
Select the UniFi Console and click on Next
Selecting a UniFi Console
1. Locate the "Filter consoles by name" search field at the top to quickly find a specific console.
2. Below the search field, you will see a list of available consoles. Options include "Brasil - UDM" and "Home - UDM Pro."
3. Select a console by clicking the radio button next to its name. For example, "Home - UDM Pro" is currently selected.
4. To proceed, click the "Next" button.
5. To return to the previous step, click the "Back" button.
Select the Network your collector is monitoring and click on Add 1 Collector
Select Collectors Interface in UDM Pro
1. The page title is "Select Collectors." It guides you to choose collectors for "Home - UDM Pro."
2. A search field labeled "Filter Collectors by name" allows you to search for specific collectors.
3. Below the search field, a collector named "Default" is displayed with a checkbox. The checkbox is checked, indicating that the "Default" collector is selected.
4. Two buttons are at the bottom: "Back" to return to the previous step and "Add 1 Collector" to confirm the current selection and proceed.
Your Domotz Collector will now integrate with the UniFi Cloud via API, generating the Topology map and enriching UniFi device details.
Ubiquiti Unifi Controller Interface Overview
1. The interface displays an informational section describing how the Domotz User Interface is enhanced with features from the Ubiquiti Unifi Controller, detailing its ability to manage switches and wireless access points and showing information about ports and connected devices. A link to the Domotz User Guide is provided for more information.
2. Below the description, there is a listed controller labeled "Home - UDM Pro," with subsections for "Sites" and "Default."
3. An option labeled "Add Controller" is available, allowing users to add new controllers to the system.
2. Username and password Method
Note: Starting July 2024, MFA became mandatory for Ubiquiti accounts. Because Domotz’s UniFi API doesn’t support MFA-protected accounts directly, you have two options: create a Local Admin Account (no MFA required), or use a Cloud Account with an MFA seed entered directly into Domotz.
2.1 Option A: Local Username and password
Use this option if you’d rather not expose an MFA seed to Domotz, or if your UniFi Controller is managed locally.
2.1.1 Create a Local Admin Account
- Log in to your UniFi Controller
- Under Admins, click to add a new admin user, and make sure the Restrict to local access only checkbox is enabled.
- Enter a username (it doesn’t need to be an email address) and set a password. Make a note of both.
- Uncheck Use a pre-defined role, and set the Network permission to Site Admin.
- Click Add.
Add Admin in a Software System
1. Enter the username in the "Username" field. For example, "domotz."
2. Type a secure password into the "Password" field.
3. Check the box labeled "Restrict to local access only" if you want to limit access.
4. Choose whether to use a predefined role by checking "Use a pre-defined role."
5. Under "Network," select "Site Admin" from the dropdown menu.
6. For "Protect," "Access," "Talk," and "OS Settings," select "Full Management" from each dropdown if full access is needed.
7. Optionally, check "Save as a pre-defined role" if you want to save this configuration for future use.
2.1.2 Connect Domotz Using the Local Admin Account
Navigate to the Domotz Webapp > Collectors > Select the collector with your UniFi network > Devices section > at the Device Configuration options click on Cloud and Local Integrations:
Accessing Cloud and Local Integrations in Device Configuration Menu
1. Navigate to the main menu and click on "Devices" to access device-related settings.
2. Expand the "Device Configuration" section on the left sidebar.
3. Select "Cloud and Local Integrations" from the list of options.
4. Use this section to manage integrations specific to your devices within the network.
In the right pane, you can view network equipment status, including total and online counts. Use the filters and selection options to organize or manage your devices effectively.
Select Connect via Username & Password and click on Next
Connecting to the Ubiquiti Unifi Controller Service
1. Choose a connection method: Select "Connect via Username & Password" to use your UniFi username and password, or select "Connect via API Key" to use a Site Manager API key.
2. After selecting your preferred method, click "Next" to proceed.
3. If you need to exit without proceeding, click "Cancel."
Add the local controller IP Address and port (the same address you use to manage it locally):
Note: Make sure you always enter your port number, like shown in the screenshot below, in case you don’t use the default one.
Connecting to the Ubiquiti Unifi Controller Service
1. Enter the controller hostname or IP address in the input field labeled "Controller Hostname or IP Address." Ensure you include the HTTPS port of your controller, as shown in the example format "192.168.86.1:8443."
2. Input your Unifi username in the designated "Unifi Username" field. Example provided: "local_user."
3. Enter your Unifi password in the field labeled "Unifi Password."
4. Note: A local admin account is required for integration with Ubiquiti Unifi Controllers. For detailed setup processes and troubleshooting, refer to the link provided in the note section.
5. If you cannot use a local admin account, click the provided link for alternative solutions.
6. After filling in all required fields, click the "Connect" button to proceed.
7. Use the "Back" button if you need to return to the previous screen.
Select the Network your collector is monitoring and click on Add 1 Collector
Select Collectors Interface in UDM Pro
1. The page title is "Select Collectors." It guides you to choose collectors for "Home - UDM Pro."
2. A search field labeled "Filter Collectors by name" allows you to search for specific collectors.
3. Below the search field, a collector named "Default" is displayed with a checkbox. The checkbox is checked, indicating that the "Default" collector is selected.
4. Two buttons are at the bottom: "Back" to return to the previous step and "Add 1 Collector" to confirm the current selection and proceed.
Your Domotz Collector will now integrate with the UniFi Cloud via API, generating the Topology map and enriching UniFi device details.
2.2 Option B: Cloud Username and Password with 2FA
Use this option if you want to connect using a Cloud (ui.com or third-party Cloud controller) account rather than a local admin account. Since Ubiquiti’s API doesn’t support MFA-protected logins directly, Domotz needs the account’s MFA seed instead.
2.2.1 Retrieve the UniFi MFA Seed
- Open an incognito browser window (or log out of your main UniFi account first).
- Create a new account at https://account.ui.com/register.
Creating a UI Account
1. Enter your desired username in the "Username" field.
2. Provide your email address in the "Email" field.
3. Create a password and type it into the "Password" field. Ensure it is secure; the system indicates when it is "very strong."
4. Re-enter the password in the "Confirm Password" field for verification.
5. Check the box to agree to the Terms of Service and Privacy Policy.
6. Optionally, check the box to sign up for newsletters if desired.
7. Click the "Create Account" button to complete the process.
8. If you already have an account, click on "Sign In" to log in.
- Configure MFA using the App Authentication option, then click Enter code manually to reveal the MFA seed code.
Set up app authentication with a QR code.
1. Scan the displayed QR code using an authentication app of your choice to set up app authentication.
2. If you cannot scan the QR code, click on "Enter code manually" to input the code in the authenticator app.
3. Once completed, click "Continue" to proceed.
4. Options to "Cancel" or "Continue" are available at the bottom of the window.
- Copy and securely save the MFA seed code. You’ll enter it into Domotz later.
- Finish setting up MFA using your preferred authenticator app.
- Log in to your main Admin account and go to the Admins page: https://unifi.ui.com/admins-list.
- Invite the new account as an Admin, using the same email address. The admin role can be global or site-specific.
Add an Admin in the Interface Settings
1. Enter the admin's email address in the "UI Account Email" field.
2. Select the site to which the admin will have access by choosing from the "Select Sites" list.
3. Choose the level of access from the dropdown under "Network." For full permissions, select "Full Management."
4. Click the “Add” button to finalize and add the admin.
- After sending the invite, wait for the confirmation email and accept it from the new account.
Make sure this new account has access to all the sites you plan to monitor.
2.2.2 Connect Domotz Using the MFA Seed
- Navigate to the Domotz Webapp > Collectors > Select the collector with your UniFi network > Devices section > at the Device Configuration options, click on Cloud and Local Integrations.
- Select Connect via Username & Password and click on Next
Connecting to the Ubiquiti Unifi Controller Service
1. Choose a connection method: Select "Connect via Username & Password" to use your UniFi username and password, or select "Connect via API Key" to use a Site Manager API key.
2. After selecting your preferred method, click "Next" to proceed.
3. If you need to exit without proceeding, click "Cancel." - In the standard connection modal, click the here link to switch to the alternative modal for entering the MFA seed.
Connecting to the Ubiquiti Unifi Controller Service
1. Enter the Controller Hostname or IP Address, including the HTTPS port.
2. Input your UniFi Username.
3. Enter your UniFi Password.
4. If a local admin account is unavailable, click the provided link for alternative solutions.
5. Click "Connect" to proceed or "Cancel" to exit.
6. For detailed setup instructions and configuration steps, use the additional links in the "Please note" section. - Fill in the required fields, including the MFA seed. If your controller doesn’t use the default port, remember to include the port number in the Controller field, as shown below.
Connect to Ubiquiti Unifi Controller Service
1. Enter the Controller Hostname or IP Address in the provided field, ensuring to include the HTTPS port (e.g., `https://192.168.77.200:8443`).
2. Input your Unifi Username in the designated field (e.g., `domotz_test`).
3. Enter your Unifi Password in the password field. The password will be masked for security.
4. Provide the MFA Seed if applicable, using the specific seed given (e.g., `JBSDEASD412D2356`).
5. To find out more about obtaining an MFA seed, click the provided link.
6. Click the "Connect" button to proceed or "Cancel" to exit without connecting. - Select the Network your collector is monitoring and click on Add 1 Collector.
Select Collectors Interface in UDM Pro
1. The page title is "Select Collectors." It guides you to choose collectors for "Home - UDM Pro."
2. A search field labeled "Filter Collectors by name" allows you to search for specific collectors.
3. Below the search field, a collector named "Default" is displayed with a checkbox. The checkbox is checked, indicating that the "Default" collector is selected.
4. Two buttons are at the bottom: "Back" to return to the previous step and "Add 1 Collector" to confirm the current selection and proceed.
2.2.3 Cloud Controller Connection
If you’re configuring a Cloud Controller (rather than a local one), you’ll need the controller URL from the Cloud Controller console.
For example, given the URL:
https://unifi.ui.com/consoles/b0dc2a0b-7f73-4217-9245-35b00a148971/network/default/settings/wifiDomotz only needs the portion up to the console ID:
https://unifi.ui.com/consoles/b0dc2a0b-7f73-4217-9245-35b00a148971Anything after that must be left out.
UniFi Network Dashboard Overview
1. Verify that the system status is operational by checking for the "All Systems Operational" message at the top.
2. To view network details for the current site, look at the panel with the site name, "Domotz Sofia."
3. Check device statistics like the number of connected devices, usage, and clients in the panel.
4. For instructions on connecting devices, click "Adoption Instructions."
5. To configure network settings, use the "Inform URL" link.
6. Confirm the server IP address, listed as "Server IP: 10.110.0.53."
7. Review the "Device Capacity" to see the current device count and capacity limit.
8. Manage your subscription using the "Manage Cloud Subscription" link.
9. Analyze network data trends displayed in the graph on the right, showing historical network performance metrics.
Use the URL as shown below when connecting to the Cloud Controller:
Connecting to the Ubiquiti Unifi Controller Service
1. Enter the Controller Hostname or IP Address in the provided field. Make sure to include the HTTPS port.
2. Input your Unifi Username in the appropriate field.
3. Type your Unifi Password in the password field.
4. Provide the MFA Seed in the designated area for Multi-Factor Authentication.
5. For assistance with obtaining the MFA seed, follow the link provided in the instructions.
6. Use the 'Connect' button to proceed or the 'Back' button to return to the previous screen.
3. Important Notes
These apply regardless of which connection method (API Key, Local Admin, or Cloud + MFA) you used:
Please note that this integration will work only on devices which can be reached by the Domotz agent on Layer 2, and for devices that reside in VLANs configured in Domotz.
For this reason, devices that reside on Layer 3 Routed Subnets will not be monitored by the Ubiquiti Unifi Integration.
Please note that for UniFi integrations, the local controller (discovered via L2 or L3 scans) must remain online and responsive – either to ARP pings (for L2-discovered devices) or to standard ICMP pings (for L3-discovered devices). If the controller is offline or unresponsive, the integration will not function properly.
Please note that when connecting an external controller, it creates a new external host device, so it consumes one managed device.
4. Features
These are some of the additional info/features that you’ll get once the UniFi controller is Connected (Cloud Controller) or Unlocked (Local Controller):
Ubiquiti UniFi AP
- Reboot
- Basic information like:
- firmware
- model
- Advanced information like:
- Monitor signal strength and noise level of APs by channel
- Monitor signal strength of connected clients
- Monitor access point traffic/hardware utilization
- etc
Ubiquiti UniFi Switches
- On/Off of PoE ports
- Port Mapping
- Port PoE consumption
4.1 Examples of Ubiquiti/UniFi Remote Monitoring and Management
Managed Devices Overview:
1. Current device name is displayed as "NASD6F855" in the interface.
2. The status of the device is indicated as "online."
3. Within the "Managed Devices" pop-up, there's a section labeled "Connected Access Points."
4. The list shows an "Ubiquiti Access Point" with a status of "20 days."
5. There is an option to "Set a location or zone" for better organization.
6. A "Reboot Now" button is available for quickly restarting the device.
Device Details and Status Overview for Ubiquiti Access Point
1. The device status is displayed at the top, showing it is currently "online" with the associated IP address, MAC address, and model information.
2. Tabs for additional settings include "Info," "Access Point," "Connect," "Alerts," and "History."
3. The status section gives details such as time since last status change (20 days ago), last status change count (0x), firmware version (4.0.21.9965), and serial number.
4. Network performance metrics provided are "Latest Ping RTD" (1ms), "Packet Loss" (0%), and "Historical Ping Range" (<1ms - 11ms).
5. An option to "Ping Now" is available for testing the connection.
6. Network mapping indicates the device is controlled by "NASD6F855" at IP address 10.53.10.156.
7. A sidebar shows sections for "Devices External Services" with a status of "Connected," "Latest Events" with timestamps of device status changes, "Latest Connections," and an option to "Create a Connection."
8. Also in the sidebar, "Latest Updated Sensors" offers an option to "Add a SNMP or TCP sensor."
Ubiquiti Access Point Radio Details
1. The dialog box displays details for two radios: Radio wifi0 and Radio wifi1.
2. For Radio wifi0:
- Channel is set to 3.
- Average RSSI is 50 dBm.
- Noise Floor value is -104 dBm.
- Status is indicated as Enabled.
- Radio Type shows as "ng".
- Rx Bytes and Tx Bytes are not provided.
3. For Radio wifi1:
- Channel is set to 48.
- Average RSSI is 50 dBm.
- Noise Floor value is -104 dBm.
- Status is indicated as Enabled.
This information is used to analyze the performance and configuration of the network's radio frequencies.
System Information Overview for a Ubiquiti Access Point
1. The top section displays usage statistics: CPU Usage at 3%, Memory Usage at 70%, Download Total at 874.7 MB, and Upload Total at 880.6 MB.
2. The system details section lists various attributes:
- Status: Online
- Connected Time: Few seconds ago
- Last Seen: March 25, 2021
- Model: U7LT
- Total Memory: 119.5 GB
- Available Memory: 35.9 GB
- Firmware Version: 4.0.21.9965
- Build Version: 33
This panel provides essential performance metrics and system specifications for managing the device.
Device Details and Actions Overview
1. At the top, the device 'PowerCable' is online with the IP address 10.53.10.174 and serial number 24A42C38E886.
2. Key information includes firmware version 2.5.1, latest ping RTD of 5ms, and historical ping range of 3ms to 26ms.
3. To perform a ping, use the 'Ping Now' button.
4. Under Network Mapping & Power Management, the device is mapped on 'Ubiquiti Access Point @10.53.10.111' with an 'Office PDU' switch to toggle power management.
5. WiFi Info shows RSSI at 50, SSID as Domotz, and the channel operating on 2.4 GHz.
6. Available actions include options for Wake On LAN, exporting, and importing device settings, along with deleting the device.
7. Tools for connections, sensors, and notes are provided on the right side, along with options to create a connection and add sensors.