UniFi Protect

FreeSDN includes a UniFi Protect adapter in the cameras module that connects to the UniFi Protect API served by UniFi OS consoles (UDM, UDM-Pro, UniFi NVR, Cloud Key Gen2+).

Caution

The UniFi Protect adapter is not the same as the UniFi network adapter. The network adapter manages switches, APs, and gateway devices through the UniFi Network Application. This page covers only the Protect camera integration.

The UniFi Protect camera adapter is at an early stage and is classified as Preview / Foundation tier in the supported vendors matrix. It is read-only (camera/NVR discovery, snapshot, and RTSP URL only), has no dual-gate writes, no circuit-breaker tagging, and has never been run against real UniFi Protect hardware. Review the limitations section before deploying in a production camera fleet.

What works

Feature	Notes
Camera discovery	List cameras registered to a Protect console
Live stream	RTSP URL retrieval from the Protect API
Snapshot	JPEG snapshot via Protect API
Camera detail	Model, firmware, resolution, recording mode
Device info	Console model, firmware, storage status

What does not work

• PTZ control - Protect API PTZ support is undocumented; commands are not exposed. Note: the adapter manifest currently declares Capability.CAMERA_PTZ for G3/G4/G5-PTZ models and discover_devices() appends Capability.PTZ for any camera whose Protect bootstrap reports featureFlags.hasPanTilt, but no PTZ methods are implemented in the adapter - any PTZ API call will return a NOT_SUPPORTED error at runtime. Treat these capability declarations as inaccurate for runtime behavior; PTZ API calls return a NOT_SUPPORTED error.
• Recording playback - searching and downloading recorded clips through FreeSDN is not implemented for Protect.
• Event ingest - motion, smart detection (person, vehicle, package) events from Protect are not ingested into the FreeSDN event bus.
• Doorbells / smart sensors - only standard IP cameras are managed.
• No frontend page yet - operators consume the REST endpoints directly; no dedicated Protect UI page exists.

Adding a UniFi Protect console

Authentication uses a UniFi local account with the Protect role on the console.

# Add the Protect console as a controller
curl -X POST https://freesdn.example.com/api/v1/controllers \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "UDM-Pro Protect",
    "controller_type": "unifi",
    "host": "10.0.0.1",
    "port": 443,
    "use_ssl": true,
    "verify_ssl": false,
    "site_id": "<site-uuid>",
    "username": "freesdn",
    "password": "s3cr3t"
  }'

# Trigger discovery
curl -X POST https://freesdn.example.com/api/v1/discovery/controllers/<controller-uuid> \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>"

Discovered cameras appear in Video Surveillance → Cameras with vendor: Ubiquiti.

Authentication notes

UniFi OS consoles authenticate through /api/auth/login (POST with username / password). The adapter stores the session cookie and re-authenticates on expiry. Two-factor authentication on the local account will cause login failures - use an account without 2FA or a local-only account.

Tip

Create a dedicated local account on the UDM/UNVR with Protect access only. Avoid using the primary admin account; if the FreeSDN credential is ever compromised, the blast-radius is limited to camera access.

Backend route prefix

UniFi Protect cameras use the cameras module routes at /api/v1/cameras/. The adapter is selected when the camera or controller record has vendor set to "unifi_protect", "unifi", or "ubiquiti" (all three map to this adapter). Note that "unifi" and "ubiquiti" are also assigned by the network scanner and auto-discovery for Ubiquiti hardware; these records will use the Protect adapter for camera operations regardless.

Field reports

File a GitHub Issue tagged adapter:unifi-protect to report field behavior.