Ubiquiti UniFi Discovery

The Infracast Ubiquiti UniFi plugin connects to the Ubiquiti Site Manager cloud API (api.ui.com/v1/) to discover your UniFi infrastructure. It enumerates all managed hosts (console devices such as Dream Machine Pro), their associated sites, every device (switches, access points, gateways) under each host, and connected clients — all without requiring a local controller URL for cloud-managed deployments.

How It Works

1. Infracast authenticates to the Ubiquiti Site Manager cloud API using an API key
2. All host devices (consoles) registered to the account are enumerated via /v1/hosts
3. All managed devices (switches, APs, gateways) are fetched via /v1/devices, which returns a nested structure: each entry is a host wrapper containing a devices[] array
4. Connected clients (wired and wireless) are collected per host
5. All resources are normalized and written to the Infracast graph

Cloud API vs. Local Controller

Infracast uses the Ubiquiti Site Manager cloud API by default — no local controller URL required. This works for all UniFi OS consoles (Dream Machine Pro, Dream Machine SE, Cloud Gateway) that are registered to a Ubiquiti account.

For air-gapped or self-hosted deployments without cloud connectivity, you can optionally provide a local controller URL. See Air-Gapped / Self-Hosted Setup below.

Prerequisites

• A Ubiquiti account with one or more UniFi OS consoles registered to it
• An API key generated from your Ubiquiti account (see below)
• Network access from the Infracast collector to api.ui.com (HTTPS/443)

Generating an API Key

1. Log in to account.ui.com
2. Navigate to API Keys (left sidebar)
3. Click Create API Key
4. Give it a descriptive name (e.g., infracast-discovery)
5. Copy the key — it is shown only once

tip

The API key grants read access to all sites and devices registered to your Ubiquiti account. Store it in a secrets manager and rotate it periodically.

Registering the Credential in Infracast

infracast creds add \
  --plugin ubiquiti-unifi \
  --name "ubiquiti-cloud" \
  --type api-key \
  --api-key-file /run/secrets/ubiquiti-api-key

Configuring the Discovery Job

infracast.yaml

discovery:
  jobs:
    - name: unifi-cloud-discovery
      plugin: ubiquiti-unifi
      credential: ubiquiti-cloud
      schedule: "0 */4 * * *"   # every 4 hours
      config:
        # Cloud API base URL (default, no changes needed for most deployments)
        api_base_url: "https://api.ui.com/v1"

What Gets Discovered

Resource Type	Description
ubiquiti.host	UniFi OS console / host device (Dream Machine Pro, Dream Machine SE, Cloud Gateway, etc.) — includes hostId, hostName, IP, firmware version, and registration status
ubiquiti.site	Logical site managed by a host (name, location metadata)
ubiquiti.device	Managed UniFi device under a host: switches, access points, gateways — includes MAC, IP, model, firmware version, product line, online status, and isConsole/isManaged flags
ubiquiti.client	Connected client (wired or wireless) — includes hostname, MAC, IP, VLAN, SSID, associated device, last-seen timestamp

Graph Relationships

• ubiquiti.host → contains → ubiquiti.site
• ubiquiti.host → contains → ubiquiti.device
• ubiquiti.device → associated_with → ubiquiti.site
• ubiquiti.client → connected_to → ubiquiti.device

API Response Structure

The /v1/devices endpoint returns a nested structure — each top-level entry is a host wrapper, not a flat device:

{
  "data": [
    {
      "hostId": "abc123",
      "hostName": "Home Network",
      "devices": [
        {
          "id": "device-uuid",
          "mac": "aa:bb:cc:dd:ee:ff",
          "name": "Dream Machine Pro",
          "model": "UDM-Pro",
          "ip": "192.168.1.1",
          "status": "online",
          "version": "4.0.21",
          "isConsole": true,
          "isManaged": true,
          "productLine": "unifi"
        }
      ]
    }
  ]
}

Infracast iterates through data[].devices[] to extract individual device nodes.

Air-Gapped / Self-Hosted Setup

For environments without internet connectivity, you can point Infracast at a local UniFi Network Application controller instead of the cloud API:

infracast.yaml

discovery:
  jobs:
    - name: unifi-local
      plugin: ubiquiti-unifi
      credential: unifi-local-creds
      schedule: "0 */4 * * *"
      config:
        # Local controller URL (overrides cloud API)
        local_controller_url: "https://unifi.example.com:8443"
        # Set to "false" for self-signed certificates (common for self-hosted)
        verify_tls: "false"

Register local credentials using basic auth:

infracast creds add \
  --plugin ubiquiti-unifi \
  --name "unifi-local-creds" \
  --type basic-auth \
  --username "infracast" \
  --password-file /run/secrets/unifi-password

Troubleshooting

401 Unauthorized from cloud API

Symptom: Error: 401 Unauthorized from api.ui.com

Checks:

1. Verify the API key is correct — keys are shown only once at creation time
2. Confirm the key has not been revoked in account.ui.com → API Keys
3. Ensure the key belongs to the same account that owns the consoles you expect to see

No devices returned

Symptom: Hosts are discovered but ubiquiti.device nodes are empty

Explanation: The /v1/devices endpoint returns a nested structure (data[].devices[]). If the account has no registered consoles, the response will be an empty data[] array.

Checks:

1. Confirm consoles are registered to the same Ubiquiti account as the API key
2. Verify the consoles are online and connected to the Ubiquiti cloud

Clients not appearing

Symptom: Devices are discovered but no clients show up

Checks:

1. Clients are only returned for active sessions. If the network is idle, no clients appear.
2. Verify your API key has access to the account hosting the consoles

TLS certificate error (local controller only)

Symptom: Error: x509: certificate signed by unknown authority

Fix: Self-hosted controllers commonly use self-signed certs. Set verify_tls: "false" or install a valid certificate on the controller.