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 id	`unifi`	`unifi-cloud`
Category	Network	Network
Authentication	UniFi API key	UniFi API key
Reaches	Your console, on your LAN	`api.ui.com`
Needs an agent	Yes, on managed hosting	No
Reports clients	Yes	No
Demo mode	Yes, off by default	Yes, off by default

Which one to configure

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, it breaks on controller upgrades, and shipping a customer-facing integration on it means owning that breakage forever.

Capabilities

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.

Preparing UniFi

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

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

TLS on a local console

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.

Configuring it in Plugboard

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

Settings, local console

Field	Default	Value
`baseUrl`	empty	Console URL, e.g. `https://unifi.school.internal`
`demoMode`	`false`	Return a sample network, making no API calls

Settings, Site Manager cloud

Field	Default	Value
`baseUrl`	`https://api.ui.com`	The Site Manager host. Leave it alone
`demoMode`	`false`	Return 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.

Secrets (encrypted)

Field	Value
`apiKey`	The 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.

The private network question

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.

What you get


Sites	Every UniFi site on the console or account, ready to map to a campus
Devices	Gateways, switches and access points with model, MAC, IP, firmware and uptime
Status	Up, down or unknown
Ports	Where the device reports them
Clients	Local 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.

What it cannot do

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.
Choose between separate consoles in every network workflow. From 0.14.0, separate local consoles can have named connector instances. Network workflows without a source selector refuse ambiguous connections; adding the instances does not yet provide a combined network view. A single console can still expose several sites through one connection.
Talk to Network Application 8 or older. The integration API is not there.

Troubleshooting

Symptom	Cause
A sample network appears	`demoMode` is still on
Certificate errors on the local console	Self-signed certificate. Trust it properly on the agent host; there is no bypass
404 on every call	`baseUrl` carries a path, or the console is on Network Application 8 or older
401	The API key was revoked, or belongs to the other console
Everything times out, self-hosted	`ALLOW_PRIVATE_EGRESS` is not set
Everything times out, managed hosting	No agent, or the agent’s host cannot reach the console
No clients, ever, on the cloud connector	Expected. Use the local console connector
No clients on the local connector	Client tracking is off. It is off until an administrator turns it on
Devices appear with no campus	Map each UniFi site to a campus on the network pane

Cisco Meraki and network hardware over SNMP fill the same pane, and everything enabled is merged rather than resolved. All the network connectors share one connector slot between them.