Skip to content
plugboard.appRequest a demo

Connectors

UniFi

Read the Ubiquiti UniFi estate into the network pane. Read only, and published as two connectors because Ubiquiti ships two usable APIs that are not interchangeable.

UniFi (local console)UniFi (Site Manager cloud)
Connector idunifiunifi-cloud
CategoryNetworkNetwork
AuthenticationUniFi API keyUniFi API key
ReachesYour console, on your LANapi.ui.com
Needs an agentYes, on managed hostingNo
Reports clientsYesNo
Demo modeYes, off by defaultYes, off by default

The local console, if you can. It reports clients, which the cloud API does not expose, and clients are what answer “where was that laptop last seen”.

The Site Manager cloud, if your consoles are adopted to a UI account and you are on managed hosting without an agent. You get the estate and its status; you do not get clients.

There is a third UniFi API: the legacy cookie and CSRF one every community script uses. It is not implemented and will not be. It is undocumented and breaks on controller upgrades.

Local console: network.listSites, network.listDevices, network.getDevice, network.listClients

Site Manager cloud: network.listSites, network.listDevices

The cloud connector deliberately does not claim network.listClients. Declaring it so the pane offers a “last seen” that is permanently empty would be worse than not offering it, because “not supported here” and “nothing found” must not look the same.

Both light up the network page, gated by module.network.

The local console needs Network Application 9.x or newer, which is where the Network Integration API appears.

  1. In the UniFi console, Control Plane, Integrations: create an API key. It is shown once.
  2. Note the console’s URL. It must be reachable from wherever the connector runs.
  3. For the cloud connector, create the key against your UI account instead; it covers every console adopted to that account.

A UniFi console presents a self-signed certificate, and this connector has no “skip certificate verification” option. It is not going to get one: a checkbox that turns verification off is a checkbox that ends up ticked on every install.

The agent runs on your own LAN, where you can trust the console’s certificate properly. Point NODE_EXTRA_CA_CERTS at it, or put a certificate on the console that your machines already trust.

Settings, Connectors, UniFi (local console) or UniFi (Site Manager cloud), then Configure.

FieldDefaultValue
baseUrlemptyConsole URL, e.g. https://unifi.school.internal
demoModefalseReturn a sample network, making no API calls
FieldDefaultValue
baseUrlhttps://api.ui.comThe Site Manager host. Leave it alone
demoModefalseReturn a sample network, making no API calls

Configure the host in baseUrl, not a versioned path. A base carrying a path has it silently discarded and produces a 404 that reads like a bad key.

FieldValue
apiKeyThe UniFi API key

Both connectors take the same field. They are separate instances with separate credentials, so a school running both pastes the key twice. A school with more than one local console adds an instance for each; a single console exposes all its sites through one instance.

A UniFi console lives on your LAN.

Self-hosted on that network: the local connector reaches it directly. You will also want ALLOW_PRIVATE_EGRESS=1, because Plugboard blocks outbound requests to private address ranges by default.

Managed hosting: the local connector needs a connector agent on a machine that can reach the console. Nobody should ever be told to open private egress on a hosted deployment to make this work. The cloud connector needs no agent.

SitesEvery UniFi site on the console or account, ready to map to a campus
DevicesGateways, switches and access points with model, MAC, IP, firmware and uptime
StatusUp, down or unknown
PortsWhere the device reports them
ClientsLocal console only, and only when client tracking is on

A device state UniFi reports that we do not recognise comes back as unknown, never as down. A vocabulary change on Ubiquiti’s side must not read as an outage across your school.

  • Write anything. Read only. No adoption, no restart, no configuration.
  • Report clients from the cloud. The Site Manager API does not expose them.
  • Report WAN uplink loss and latency. Neither UniFi API surfaces them in the shape the pane wants; the uplink row is not populated from UniFi.
  • Talk to Network Application 8 or older. The integration API is not there.
SymptomCause
A sample network appearsdemoMode is still on
Certificate errors on the local consoleSelf-signed certificate. Trust it properly on the agent host; there is no bypass
404 on every callbaseUrl carries a path, or the console is on Network Application 8 or older
401The API key was revoked, or belongs to the other console
Everything times out, self-hostedALLOW_PRIVATE_EGRESS is not set
Everything times out, managed hostingNo agent, or the agent’s host cannot reach the console
No clients, ever, on the cloud connectorExpected. Use the local console connector
No clients on the local connectorClient tracking is off. It is off until an administrator turns it on
Devices appear with no campusMap each UniFi site to a campus on the network pane

Cisco Meraki and network hardware over SNMP fill the same pane. Every enabled network connector instance, including several UniFi consoles, is read and the pane combines the results. Meraki, UniFi and SNMP network hardware count as one connector against your plan’s connector allowance, however many of them, or instances of them, you configure.