Ubiquiti UniFi

The UniFi adapter manages Ubiquiti UniFi controller-managed switches, access points, and security gateways via the UniFi Network Application API.

Fact	Detail
Maturity	Production
Hardware validation	Live-validated on a real UCG Fiber (UniFi OS 5.1.19 / UniFi Network 10.4.57), classic (v1) + modern (v2) API lanes
Test coverage	136 passing tests
Gold-standard contract	DG ✓ CB ✓ RR ✓ TS ✓ SSRF ✓ RG ✓
Frontend UI	UniFi firewall drawer; no dedicated full management UI yet

Console detection

The adapter auto-detects the console type at init:

UniFi Network Application (Classic) - e.g., self-hosted on :8443; uses /api/login auth endpoint.
UniFi OS consoles - UDM, UDM-Pro, Cloud Key Gen2+; uses /api/auth/login with /proxy/network/api/ prefix for network API calls.

No configuration flag is required; the adapter probes the controller at startup and selects the correct auth flow.

What works

Read paths (19 methods - all redact secrets on return)

Method	Description
`list_sites`	All sites on the controller
`get_site_health`	Site-level health summary
`list_devices`	Switches, APs, gateways
`get_device`	Single device detail
`list_port_overrides`	Port profile assignments
`list_clients`	Connected clients
`get_client`	Single client detail
`list_networks`	VLANs, subnets, DHCP scopes
`get_network`	Single network detail
`list_wlans`	Wireless networks (PSK stripped on read)
`get_wlan`	Single WLAN (PSK stripped on read)
`list_firewall_rules`	Firewall rules
`list_firewall_groups`	Firewall groups
`list_port_forwards`	Port forwarding rules
`list_radius_users`	RADIUS users
`list_vpn_clients`	VPN clients
`get_controller_info`	Controller version and metadata
`get_sysinfo`	System resource usage
`list_alerts`	Active alerts

Write paths (9 methods - all dual-gated + audit-logged)

Every write requires ADAPTER_READ_ONLY=false in the environment and force: true on the apply request body. Every endpoint enforces a minimum site_admin role. Every successful write emits a structured unifi.write_attempted audit log line (PSK is never logged).

Method	Description
`restart_device(site, mac)`	Reboot an AP or switch
`update_port_override(site, device_mac, port_idx, profile_id)`	Assign VLAN / PoE profile to a port
`set_port_poe(site, device_mac, port_idx, mode)`	Set PoE mode: `auto` / `off` / `passive24` / `passthrough`
`update_wlan_password(site, wlan_id, new_psk)`	Rotate a WLAN PSK
`enable_wlan(site, wlan_id, enabled)`	Toggle WLAN broadcast on/off
`block_client(site, client_mac)`	Block a client
`unblock_client(site, client_mac)`	Unblock a client
`forget_client(site, client_mac)`	Remove a client from controller memory
`disable_device(site, device_mac, disabled)`	Admin-disable a device without removing it

What does not work yet

No dedicated full management UI (a UniFi firewall drawer exists; other domains are REST-only).
Topology API is not available in this release.
SDN backup / restore endpoints.
Layer 2/3 device adoption flows (manual SSH adoption only).
The broad write surface beyond VLAN/network create + delete was exercised live but is not yet persisted per domain via cassette.

Backend route prefixes

/api/v1/unifi/{controller_id}/sites/
/api/v1/unifi/{controller_id}/sites/{site}/devices/
/api/v1/unifi/{controller_id}/sites/{site}/clients/
/api/v1/unifi/{controller_id}/sites/{site}/networks/
/api/v1/unifi/{controller_id}/sites/{site}/wlans/
/api/v1/unifi/{controller_id}/sites/{site}/firewall/
/api/v1/unifi/{controller_id}/system/info
/api/v1/unifi/{controller_id}/system/sites/{site}/sysinfo
/api/v1/unifi/{controller_id}/system/sites/{site}/alerts

See /api/v1/docs for the full OpenAPI schema.

Connection requirements

Credentials

Field	Value
`credential_type`	`username_password`
`username`	UniFi controller local administrator username
`password`	Administrator password

Controller URL

For Classic (self-hosted on port 8443):

https://unifi.example.com:8443

For UDM / UDM-Pro / Cloud Key Gen2+:

https://192.168.1.1

The adapter appends the correct API prefix automatically after detecting the console type.

Adding the controller

# Create the controller record (credentials are stored inline  -  no separate /credentials step)
curl -X POST https://<freesdn-host>/api/v1/controllers \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "unifi-prod",
    "controller_type": "unifi",
    "host": "https://unifi.example.com:8443",
    "port": 8443,
    "site_id": "<site-uuid>",
    "username": "admin",
    "password": "<controller-password>"
  }'

# Verify discovery
curl https://<freesdn-host>/api/v1/unifi/<controller-id>/sites \
  -H "Cookie: freesdn_access=<token>"

curl https://<freesdn-host>/api/v1/unifi/<controller-id>/sites/default/devices \
  -H "Cookie: freesdn_access=<token>"

Enabling write operations

See the Adapter Overview for the dual-gate explanation. For UniFi specifically:

Set ADAPTER_READ_ONLY=false in your environment file.
Restart the API: docker compose --env-file .env.pro up -d api.
Issue the write directly to the REST endpoint with force: true in the request body (e.g., POST /api/v1/unifi/{cid}/sites/{site}/devices/{mac}/restart with body {"force": true}). The adapter executes the action immediately on the live controller. There is no separate apply step for these endpoints - the force flag in the body IS the explicit operator confirmation.