How to set up a UniFi captive portal with an external portal server

UniFi’s built-in hotspot portal is fine for getting guests online, but it does nothing to help you reach them again. An external portal server lets you show guests your own branded sign-up page instead, collect their name and email, and send them straight to your mailing list.

This guide walks through setting up a UniFi captive portal with WiFi Broker as the external portal server. Menu names in UniFi Network move around between versions, so if something isn’t exactly where we describe, look for the closest match.

What you need

• A UniFi OS console running a recent version of UniFi Network that supports API keys, such as a Dream Machine, Cloud Gateway or Cloud Key Gen2.
• A controller URL that is reachable from the internet over HTTPS. WiFi Broker calls your console’s API to authorise each guest, so it needs to be able to reach it.
• A guest WiFi network (SSID) for your visitors.
• A Mailchimp or Brevo account with a list for your guests.

Step 1: Create a UniFi API key

In UniFi Network, open Settings → Control Plane → Integrations and create a new API key. Give it a name you will recognise, such as “WiFi Broker”, and copy the key somewhere safe, as you will only see it once.

Step 2: Find your UniFi site name

UniFi Network can run several sites on one console. Each has a short name that appears in the URL when you open it, such as /manage/default/dashboard. For most single-site consoles the site name is simply default.

Step 3: Add your venue to WiFi Broker

Sign in, open Sites and add a new site. You will be asked for:

• Name and subdomain: your portal is served from this subdomain, for example yourvenue.wifi.broker.
• Controller URL, API key and site name: the details from steps 1 and 2.
• Mailing list: your Mailchimp API key and audience ID, or your Brevo API key and list ID. See our Mailchimp and Brevo pages for where to find these.
• Branding: your logo for light and dark mode, your terms of use and your website address.

Step 4: Turn on the hotspot portal in UniFi

Back in UniFi Network, open the settings for your guest WiFi network and turn on the hotspot (guest portal) option. Then open the hotspot or guest portal settings and:

1. Choose External portal server as the authentication type.
2. Enter your venue’s portal address, for example yourvenue.wifi.broker.
3. Save your changes.

When a guest joins the network, UniFi sends them to your portal along with their device details. Once they sign up, WiFi Broker asks your console to authorise that device, and they are online.

Step 5: Test it

Take a phone, forget the guest network if you have joined it before, and connect again. You should see your branded sign-up page. Enter your details, tap the button, and check that:

• Your phone gets online and shows the success page.
• You appear in your Mailchimp audience or Brevo list.

Troubleshooting

The sign-up page doesn’t appear

Check that the hotspot portal is turned on for the right WiFi network, and that the external portal address is spelt correctly. Some devices cache the network, so forget it and reconnect.

The page appears but the guest isn’t connected

This usually means WiFi Broker can’t reach your console. Check the controller URL is reachable from outside your network, the API key is correct, and the site name matches the one in UniFi.

Guests connect but don’t appear in my list

Check the API key and list ID in your site settings. Contacts who have previously unsubscribed from your list stay unsubscribed, so test with an address that hasn’t.

Ready to try it? See how WiFi Broker works with UniFi.