Ubiquiti UniFi

UniFi captive portal setup, start to finish

Enable the hotspot portal, point it at an external portal server, allow the domain before authorization, and give VoqadoWiFi a login it can use. Two things decide whether it works on the first try: the internal site id, and whether the internet can reach your controller.

Print my UniFi settings Is my controller supported?

Updated 9 October 2026, checked against the integration code.

Reviewed by Pierre Subeh, Founder, VoqadoWiFi · Written by the VoqadoWiFi team · Updated 9 October 2026

How do I set up a captive portal on UniFi?

In the Network application enable the hotspot portal on your guest SSID, choose External Portal Server and enter www.voqadowifi.com. Guests then land on /guest/s/<site>/. Add www.voqadowifi.com and voqadowifi.com to Pre-Authorization Access, create a local admin, and save the controller address and internal site id in the dashboard.

Pick your controller first

The hotspot settings are the same everywhere. What changes is the login the integration uses, the port, and how the internet reaches the controller.

UniFi controllers and what changes
Controller	Login and port	Site and reachability
UDM Pro, UDM SE, UDM, UDR	UniFi OS, HTTPS on 443	Usually `default`; console is often the gateway
Cloud Gateway	UniFi OS, HTTPS on 443	`default` on every unit, so register access point MACs
Cloud Key	Gen2 and later: UniFi OS on 443. First generation: `:8443`	Sits behind your router, so needs a port or a tunnel
Self hosted Network Server	Older login path on `:8443`	One server, one site per venue, nothing open at the venue

The eight steps

Find your internal site id
Open the Network application with the venue’s site selected and read the address bar. The segment in /manage/site/<id>/ is the id. Only the first site on a controller is default; later ones get generated ids such as m8en8ejk, and renaming a site never changes its id.
Turn on the hotspot portal for the guest SSID
In Settings, WiFi, edit the guest SSID and enable the hotspot or guest portal. Keep the SSID open; the portal is the gate.
Choose External Portal Server and enter the host
In the hotspot settings set authentication to External Portal Server and enter www.voqadowifi.com. UniFi always sends guests to the fixed path /guest/s/<site>/ on that host. If your version asks for an IP address, switch on Redirect using hostname and enter the host there.
Add the pre-authorization entries and leave HTTPS redirection off
Add www.voqadowifi.com and voqadowifi.com to Pre-Authorization Access. If an HTTPS Redirection toggle exists, leave it off; it is the usual source of certificate warnings. Why each entry is there.
Create a local admin for the integration
Under Admins and Users add an account restricted to local access, with Network application access and no two factor prompt. A ui.com cloud account cannot log in to the controller API.
Make the Network application reachable
UniFi has no redirect token, so VoqadoWiFi logs in to your controller for every guest. The controller needs an HTTPS address the internet can reach: a self hosted server on a VPS, a forwarded port on the console, or an outbound tunnel.
Save the controller in the dashboard and pick the site
Set the network vendor to Ubiquiti UniFi, enter the controller URL (no port for UniFi OS consoles, :8443 for a self hosted server), the local admin, and leave Console Type on Auto-detect. Test Connection lists every site as id and name; click yours.
Test on a phone that has never joined
With mobile data off, join the guest SSID. The phone should open https://www.voqadowifi.com/guest/s/<site>/, be passed to your branded portal, and be online within a few seconds of submitting the form.

What happens when a guest connects

The phone joins the guest SSID and UniFi redirects it to https://www.voqadowifi.com/guest/s/<site>/ with id (the device MAC), ap (the access point MAC), t (a timestamp), url (the page the guest wanted) and often ssid. VoqadoWiFi finds the venue by that site id and passes the guest to its branded portal.

Unlike Omada there is no token. When the guest submits the form, VoqadoWiFi logs in to your controller with the stored local admin and sends authorize-guest for the device MAC with a session length in minutes and the access point MAC. On a UniFi OS console that call goes to /proxy/network/api/s/<site>/cmd/stamgr; on a self hosted server or first generation Cloud Key, to /api/s/<site>/cmd/stamgr.

Each attempt has an 8 second limit and there are two attempts. A rejected login is not retried, because a wrong password will not fix itself. If authorization fails, the guest sees a screen saying their details were saved and how to reconnect, and Portal Health records the error kind.

The site id trap

When you create a site you give it a friendly name, such as “Harbour Bar Main”. UniFi assigns it an internal id at the same time, and every path uses the id. Put the friendly name in the dashboard and the portal loads, your logo appears, the form submits, and then nothing happens, because the authorization is aimed at a site that does not exist (api.err.NoSiteContext).

A guest who reaches a venue that is not linked at all sees a page that names the site VoqadoWiFi looked for, which tells you exactly what to fix. The fastest route to the right id is Test Connection in the dashboard: it lists every site the account can see as id and display name.

Two venues on one site name

Single site consoles call their site default. When two venues on separate consoles both send guests to /guest/s/default/, VoqadoWiFi matches the ap MAC against each venue’s registered access points. Register every access point MAC on the location, or guests at the newer venue may see the older venue’s portal.

Reaching the controller

Three ways to make the Network application reachable
Option	Best for	Open ports at the venue
Self hosted server on a VPS	Groups and new deployments	None
Forward a port to the console	One venue with a public address	TCP 443 (UniFi OS) or 8443 (older controller)
Outbound tunnel to the console	Venues behind carrier grade NAT	None

The integration accepts the factory self signed certificate on UniFi controllers. If your firewall needs a single address to allow, the platform can send controller calls through a fixed egress address; ask through the contact page whether that is enabled for your account before you rely on it.

What UniFi already does for free

Built in UniFi hotspot versus an external portal
Capability	UniFi on its own	With an external portal
Terms page	Yes	Yes
Vouchers and simple password	Yes	Email sign in instead
Payment for access	Yes	Not offered
Keep the guest email address	No	Yes, with consent recorded
Send a review request after the visit	No	Yes, to guests who agreed to email, once guest email is live at your venue
Guest list with repeat visit history	No	Guest list on every plan; visit history on Growth
Export the list	No	Yes, CSV at any time

UniFi questions

What is a UniFi external portal server?

The setting that tells UniFi to redirect unauthenticated guests to a host you choose instead of its own login page. The external service then logs in to the controller and authorizes each device once the guest has signed in.

Do I type the full portal URL or just the host?

The host, www.voqadowifi.com. UniFi adds the fixed path /guest/s/<site>/ itself, so guests arrive at https://www.voqadowifi.com/guest/s/<site>/ with the device and access point MACs attached.

Why is my portal loading but nobody gets online?

The usual causes are the wrong site id, a controller the internet cannot reach, or a login the controller rejects. Portal Health in the dashboard shows the error kind for every attempt: network, timeout, ssl, auth or controller.

Does this work behind a tunnel or reverse proxy?

Yes. UniFi OS returns its CSRF token in a header and inside the TOKEN cookie, and some proxies drop the header. The integration reads the cookie when the header is missing, so a tunnelled console still authorizes guests.

Which UniFi controllers are supported?

UniFi OS consoles such as the UDM family, UDR, UniFi Express, Cloud Gateways and Cloud Key Gen2 and later, plus the self hosted UniFi Network Server and the first generation Cloud Key. Console Type Auto-detect tells the two generations apart.

Can I use unifi.ui.com instead of exposing the controller?

No. Ubiquiti’s Site Manager API at api.ui.com lists hosts and devices but cannot authorize guests, so the Network application itself must be reachable.

Can I charge for WiFi with this?

No. UniFi’s own hotspot can take payment for access; VoqadoWiFi does not. If you want to keep who came in rather than charge them, it is the other way round.

When something is not working

Deeper reading

The longer UniFi articles from the blog. Where an article and this page disagree, this page is the one checked against the current integration.

UDM Pro guest WiFi portal setup. UniFi OS specifics and firmware update habits.
Exposing a UniFi controller with Cloudflare Tunnel. Reachability with no port forwarding.
One controller, every venue: UniFi on a VPS. The architecture for groups.
How the captive portal mini browser behaves
Guest VLAN segmentation
Guest bandwidth management

Keep reading

UDM Pro guest portal setup UniFi Cloud Gateway setup UniFi Cloud Key setup Self hosted UniFi Network Server Walled garden domains for Omada and UniFi Which access points support an external portal The same walkthrough for TP-Link Omada

Ubiquiti and UniFi are trademarks of Ubiquiti Inc. VoqadoWiFi is not affiliated with, endorsed by, or sponsored by Ubiquiti. Menu labels move between Network application releases; the setting stays with the guest SSID’s hotspot portal options.

Get the free Guest WiFi Launch Pack

Four worksheets for switching guest WiFi on at your venue: a network inventory, a launch acceptance checklist, a change window plan and a staff handoff. Works for Omada and UniFi setups.

Connect your UniFi controller free Create the free account, add your venue, and Test Connection lists your site ids. One location and 500 guest logins a month, no card. Create your free account