david/homelab-dashboard
1
0
Fork 0
Code Issues Pull requests Projects Releases 76 Packages 1 Wiki Activity Actions
Page: UniFi Network
Pages
Container Registry Documentation Screenshots Grimmory Home Kavita Lab View Module Setup Navidrome Notifications Plex Proxmox Roadmap Security Hardening Seerr Requests Storage Health UniFi Network Uptime Kuma White Labeling
15 UniFi Network
david edited this page 2026-06-03 10:25:49 -07:00
Table of Contents

UniFi Network

Dashboard Status

This module is live. The dashboard can use either UniFi Cloud/Site Manager APIs or a local UniFi Network Integration API.

Admin Fields

  • UniFi URL
  • API Key
  • Site ID (optional)
  • Cloud Console/Host ID (optional)

API Modes

UniFi Cloud

For a cloud-connected Dream Machine or UniFi OS console, use:

UniFi URL: https://api.ui.com
API Key: Site Manager API key

The dashboard reads Site Manager data and then uses the Cloud Connector proxy path for Network Integration API calls:

/v1/sites
/v1/hosts
/v1/connector/consoles/{hostId}/network/integration/v1/sites/{siteId}/devices
/v1/connector/consoles/{hostId}/network/integration/v1/sites/{siteId}/clients

Device, client, and WAN detail currently use the proxy-shaped Network Integration route:

/v1/connector/consoles/{hostId}/proxy/network/integration/v1/sites/{siteId}/devices
/v1/connector/consoles/{hostId}/proxy/network/integration/v1/sites/{siteId}/clients

If the dashboard cannot infer the console host, use the admin Discover UniFi sites button and save the discovered Cloud Console/Host ID.

Cloud discovery can return both Site Manager sites and Network connector sites. Prefer an option labeled Network connector site when available. The Network connector site ID is the ID used by the richer devices/clients/WAN endpoints; it may differ from the Site Manager site ID.

Local UniFi Network

For local-only access, use the local Network application URL:

UniFi URL: https://192.168.1.1
API Key: local Network Integration API key

The dashboard uses:

/proxy/network/integration/v1/sites
/proxy/network/integration/v1/sites/{siteId}/devices
/proxy/network/integration/v1/sites/{siteId}/clients

If Site ID is blank, the first returned site is used.

What The Card Shows

  • Summary tiles for devices, clients, APs, and switches.
  • Internet health with public address, ISP/status/latency/loss/rates when UniFi exposes WAN data.
  • Gateway Health details such as firmware, CPU, memory, uptime, and temperature when device metadata includes them.
  • Offline device warnings when UniFi reports devices as disconnected.
  • A compact network device grid focused on up/down/warning state.

Some of these fields are version and permission dependent. UniFi Cloud/Site Manager fallback may only expose device inventory, while the connector/local Network Integration API can expose richer client, WAN, and health details.

Open the card Details view when you need client detail, connector diagnostics, API visibility, or API field names. The field list intentionally contains field names, not secret values.

Find API Key And IDs

  1. Open UniFi Site Manager or the local UniFi Network application.
  2. Create an API key with access to the console/site.
  3. Enter the URL and API key in the dashboard admin page.
  4. Click Discover UniFi sites.
  5. Pick the discovered site/console values when the names are recognizable.
  6. Save Site ID and Cloud Console/Host ID when needed.

Test From The Docker Host

Cloud:

curl -fsSL \
  -H 'X-API-Key: YOUR_API_KEY' \
  'https://api.ui.com/v1/sites'

Local:

curl -k -fsSL \
  -H 'X-API-Key: YOUR_API_KEY' \
  'https://192.168.1.1/proxy/network/integration/v1/sites'

Common Problems

  • 401: wrong API key or key not valid for this API mode.
  • 403 access denied: user is not the owner of this host: Site Manager key cannot access the selected console host.
  • Sites show hashed IDs: use the discovery output and host details to choose the owner console, or manually paste the known host ID.
  • Client count missing in Site Manager fallback: fallback device data may not include client data.
  • 400 from connector endpoints: rerun Discover UniFi sites and choose a Network connector site entry if one appears. Site Manager site IDs and Network connector site IDs can differ.
  • Site Manager fallback: both cloud connector routes failed, so the dashboard used high-level Site Manager inventory instead. Try the local Dream Machine URL if the dashboard container can reach it.
  • Self-signed certificates on local consoles: use a trusted reverse proxy when possible.

Sources