UDM Pro Guest WiFi Portal Setup: The UniFi OS Specifics That Trip Everyone Up

Why the UDM Pro Deserves Its Own Guide

The UDM Pro and its siblings, the UDM SE, UDM, UDR, and the Cloud Gateway line, are the most common UniFi setup we see in new venues, and they are also the most common source of a very specific class of integration failure. Operators follow a guide written for the classic self-hosted controller, everything looks right, and the authorize call fails anyway.

The reason is that these devices run UniFi OS. The Network application is one app among several on the console, and UniFi OS puts itself in front of every request. That changes three things that captive portal integrations depend on: the port, the login endpoint, and the API path prefix. None of this is documented in one place by Ubiquiti, so here it is.

The Three UniFi OS Differences

1. The port is 443, not 8443. Classic controllers answer on 8443. A UniFi OS console serves everything, UI and API alike, on standard HTTPS port 443. If your portal platform is configured with port 8443 against a UDM Pro, every call times out.

2. Login happens against UniFi OS, not the Network app. The classic login endpoint is /api/login. On UniFi OS the login endpoint is /api/auth/login, and it authenticates you against the console itself. A successful login returns a session token as a cookie, and the console also issues a CSRF token that state-changing requests must echo back in a header. VoqadoWiFi handles this exchange automatically when you select the UniFi OS controller type, but if you are debugging with your own scripts, a missing CSRF header is the classic cause of mysterious 401 responses on POST requests that follow a successful login.

3. Network API calls are prefixed with /proxy/network. On a classic controller, authorizing a guest is a POST to /api/s/default/cmd/stamgr. On a UniFi OS console the same call is /proxy/network/api/s/default/cmd/stamgr. The proxy prefix routes the request through UniFi OS to the Network application. Forget the prefix and you get a 404 that looks like the controller has no such API at all.

In the VoqadoWiFi location settings, choosing UniFi OS as the controller type applies all three differences for you. The rest of this guide covers the setup around that.

Creating the Right Admin Account

Do not integrate with your Ubiquiti cloud account. On the console, create a dedicated local admin:

1. Open UniFi OS settings on the console, go to Admins and Users, and add a new admin.
2. Choose restricted access with a role that covers the Network application. Full Management for Network is sufficient; it does not need access to Protect, Talk, or any other app.
3. Set local access only with a username and password. Skip the email invitation flow, which creates a cloud-linked account.
4. Do not enable two-factor on this account. Automated API logins cannot answer an MFA prompt.

Use a long random password and store it properly. This account exists for exactly one purpose.

Configuring the Guest Network and Portal

The guest network setup is standard UniFi: create the guest SSID, enable the guest policy, put it on its own VLAN, and enable the hotspot portal in External Portal Server mode pointing at your VoqadoWiFi portal host. The general flow, walled garden included, is covered step by step in the UniFi external captive portal guide, and everything there applies to the UDM Pro unchanged.

One UDM-specific note: because the gateway, the controller, and the switching often live in the same box, it is easy to accidentally leave the guest VLAN with routes into your management network. Check the guest network's isolation settings explicitly, and verify from a guest device that the console's own management address is unreachable. A guest who can load your controller login page is a finding, not a feature.

Reaching a Controller Behind NAT

Here is the structural issue: your UDM Pro sits inside the venue. VoqadoWiFi's servers are on the internet, and they need to deliver an authorize call to the console every time a guest completes the portal. Something has to make the console reachable. You have three realistic options.

Option 1: Port forwarding with source restrictions. If the UDM Pro is itself your edge router, you can expose 443 to the internet, restricted to the source addresses of your portal platform. This is workable but it is the least good option: you are exposing your management plane, you must keep the source list current, and if the venue's ISP hands you CGNAT instead of a public address, it does not work at all.

Option 2: A tunnel outward. Run a lightweight connector inside the network that opens an outbound connection to a relay, so nothing inbound is ever exposed. Cloudflare Tunnel is the tool we recommend for this, and it deserves its own walkthrough: exposing a UniFi controller safely with Cloudflare Tunnel. This is the best answer for most venues, and it also survives CGNAT.

Option 3: Do not host the controller in the venue at all. For multi-venue operators, the cleanest architecture is a central self-hosted UniFi Network Server on a VPS with one site per venue, with the local hardware acting as devices only. That pattern is covered in the central UniFi server on a VPS guide. Note that this replaces the UDM's controller role, so it is an architectural decision, not a tweak.

Testing the API Path Directly

When something fails, test the layers in order rather than re-running the whole flow.

1. From an outside network, confirm the console answers on 443 at whatever hostname you exposed.
2. Confirm login works: a POST to /api/auth/login with the local admin credentials should return a success response and a session cookie.
3. Confirm the prefix: a GET to /proxy/network/api/s/default/stat/health with the session should return Network application health data.
4. Only then test a guest authorization end to end from a phone.

Ninety percent of UDM Pro integration failures show up at step 1 or step 3. If health data comes back, the marketing layer almost always works on the first try.

Firmware Updates and What They Break

UniFi OS and the Network application update on their own cadences, and majors occasionally move settings around. Two practical habits keep you out of trouble. First, do not auto-update the console the night before a busy weekend; apply updates at the start of a quiet week and re-run the guest test afterwards. Second, after any major Network application update, verify three things: the external portal is still enabled, the walled garden entries survived, and a test guest still gets authorized. That is a five minute check that has saved a lot of Friday nights.

The Payoff

None of this complexity exists for the guest. What they experience is joining your WiFi, seeing a branded page for a few seconds, and being online. What you get is a verified contact and a visit record for every opted-in guest, feeding the analytics and automation layer that actually justifies the setup work.

If you already own a UDM Pro, you already own everything the hardware side needs. The Starter plan is free for a single location, so the only investment left is the hour of configuration this guide just walked through.