UniFi Integration

Connect CaptiFi to your Ubiquiti UniFi network. This guide covers the complete setup for UniFi Dream Machine (UDM), Cloud Key, and self-hosted controllers.

Important

The portal server IP and domain must be entered exactly as shown. Incorrect values will prevent the captive portal from working.

Prerequisites

• UniFi controller (UDM, UDM Pro, UDM SE, UCG Ultra/Max, Cloud Key, or self-hosted)
• Controller firmware 6.x or later (API Key method requires UniFi Network 9.1.105+)
• Admin access to the UniFi controller
• CaptiFi account at my.captifi.io

Overview

The UniFi integration involves these steps:

1. Controller Access — Make your UniFi controller accessible to CaptiFi (firewall rule or API key)
2. Controller Connection — Link your controller to CaptiFi
3. Captive Portal Configuration — Set up the external portal redirect
4. Test — Verify guests are redirected to your splash page

---

Step 1: Controller Access

CaptiFi needs to communicate with your UniFi controller to manage guest networks and authorise devices. Choose the method that matches your setup. If your console sits behind another router and you cannot port forward, skip to Controller Behind Another Router (Double NAT / No Public IP).

Recommended: API Key Method (UniFi Network 9.1.105+)

If your controller supports API keys, this is the more secure and simpler method. Note that CaptiFi still needs to reach your controller from the internet (firewall rule or port forwarding below), unless you use the Remote Tunnel. Jump to Step 2 and choose Connect via API Key.

UDM / UDM Pro / UDM SE — Firewall Rule

On a UDM, the UniFi controller runs on the gateway itself. You need a firewall rule that allows CaptiFi's servers to reach the gateway on specific ports. This is a Firewall Rule (not Port Forwarding), because the traffic is destined for the gateway, not a device behind it.

1a: Create a Port Group

1. Open the UniFi OS console
2. Go to Settings → Firewall & Security → Firewall Rules
3. Go to Port Groups (or Groups → Port Groups depending on firmware)
4. Create a new port group:
   • Name: Captifi
   • Ports: 80, 443

1b: Create the Firewall Rule

1. Still in Settings → Firewall & Security → Firewall Rules
2. Click Create New Rule and configure:

Setting	Value
Name	CaptiFi Access
Action	Allow
Source Zone	External
Source Type	Any
Source Port	Any
Destination Zone	Gateway
Destination Type	Any
Destination Port	Port Group → Captifi
IP Version	IPv4
Protocol	All
Auto Allow Return Traffic	Enabled

3. Save the rule

What does this rule do?

This creates a WAN-to-Gateway allow rule scoped by port group. It permits any device on the internet to reach your gateway on ports 80 and 443 only. The Gateway destination zone means traffic targets the router itself (where the UniFi controller runs), not devices on your LAN. Return traffic is automatically allowed via the stateful Auto Allow Return Traffic setting.

IPv6 Note

This rule applies to IPv4 only. If your network has IPv6 enabled, you may need a separate rule for IPv6 traffic, or ensure IPv6 is not in use for the controller.

Cloud Key / Cloud Key Gen2

The Cloud Key is a separate device on your LAN, so you need traditional Port Forwarding on your router to make it accessible from the internet.

1. Log in to your router/gateway admin panel
2. Find Port Forwarding settings
3. Create a new rule:
   • External Port: 8443
   • Internal IP: Your Cloud Key's IP address
   • Internal Port: 8443
   • Protocol: TCP
4. Save

If you cannot port forward (for example your router sits behind an ISP modem/router combo, or your ISP uses CGNAT), see Controller Behind Another Router (Double NAT / No Public IP).

Self-Hosted Controller

This covers UniFi Network Server installed on your own machine, including UniFi OS Server on Windows, Linux, or a VM.

Ensure port 8443 (default) is reachable by CaptiFi on your server/VM.

You do not need to expose that port to the whole internet. Restrict inbound access on your firewall to CaptiFi's server address only:

46.62.168.7

That keeps the connection working while removing your controller from public view. Combined with an API key (which you can revoke at any time, unlike an admin password) this is the recommended setup for a self-hosted controller.

Restricting by IP? Use an IPv4 address

Enter your controller address as an IPv4 address (or a hostname with only an A record). CaptiFi then always connects from 46.62.168.7, so the single allow rule above is all you need.

Using a Custom External Port

You do not have to expose the controller's own port. You can forward any external port of your choice to it and give CaptiFi the address with that port:

1. On your firewall, create a port forwarding rule, for example:
   • External Port: 7443 (any free port you like)
   • Internal IP: your controller
   • Internal Port: 8443 (or whatever port your controller listens on)
   • Protocol: TCP
2. In CaptiFi, enter your controller address with the port, for example unifi.example.com:7443 or 203.0.113.10:7443.

CaptiFi tests the port you specify first, and every later connection (guest authorisation included) uses the same address. Combine this with the firewall restriction above so only CaptiFi's IP can reach your chosen port.

Updating an Existing Connection

If your site is already connected and you later move the controller, switch to a custom port, rotate the sign-in details, or change your API key, you can update the connection yourself, no support ticket needed.

On my.captifi.io, go to Locations, open your venue's connection status, and choose Update connection. What you see depends on how the venue is connected:

• Username and password: enter the new address (include the port if it is not 443), test it, and sign in. You can also choose Use an API key instead to switch the venue over to an API key, the simpler, more secure method (no controller login or two-factor needed).
• API key: paste the new key. If the venue reaches CaptiFi over the Remote Tunnel, its address is managed for you and only the key can change.

On app.captifi.io (classic), go to My Sites: use Update connection to change a username/password connection, or Update API key to change (or switch to) an API-key connection.

Your current connection keeps working until the new details are verified, so guest WiFi is not interrupted. If you are tightening your firewall at the same time, do it in this order: add the new port forward and allow rule first, update the connection in CaptiFi, then close the old port.

Re-applying settings after a controller reset

If your UniFi controller was factory-reset or its captive-portal settings drifted (guests suddenly see the controller's own page instead of yours), open the venue's connection status and choose Re-apply settings (on app.captifi.io it is the Re-apply settings action under My Sites). This re-pushes CaptiFi's captive portal, the allowed-addresses list guests can reach before signing in, and any speed limits, and recreates the guest WiFi network only if it is missing (it never makes a duplicate). It is safe to run at any time and does not disconnect guests who are already online. Available for self-hosted and API-key UniFi controllers (not UniFi Cloud). Note: it restores CaptiFi's standard captive-portal configuration, so any manual walled-garden or portal tweaks you made directly in UniFi are reset.

The Remote Tunnel is not available for self-hosted controllers or Cloud Keys

The Remote Tunnel removes the need for any inbound port, but its installer only runs on UniFi OS gateway consoles (Dream Machine, UCG, Dream Router, Express). It cannot be installed on a Windows, Linux, or VM-based controller, and Cloud Keys cannot run it either: their operating system does not support the tunnel, so Cloud Key sites use port forwarding instead.

If you need zero inbound exposure, either use the firewall restriction above, or move your controller onto a UniFi OS console. Contact support if you would like help deciding.

Changing which WiFi network the portal gates

If the sign-in page is showing on the wrong WiFi network (for example on a private staff network instead of your guest one), or you want to move it to a different SSID, you can swap it at any time. There is no need to redo any setup.

On my.captifi.io, go to Locations, open the venue's connection status, and choose WiFi network. On app.captifi.io (classic) the same tool is the WiFi network action under My Sites.

The picker lists every WiFi network on your controller, with the number of devices currently connected to each and a Portal active badge on the network the portal currently gates. Pick the network guests should sign in on, or choose Create a new guest network and type a name, then Apply. CaptiFi gates your pick and removes the sign-in page from any other network it was on, so a private network never stays walled by mistake.

• Pick your guest network, not a busy private one. Every device on the chosen network must complete the sign-in page. The device counts in the picker help you spot which network your staff gear lives on.
• Newer consoles: check the Hotspot zone too. On gateways with zone-based firewalling (new Dream Machines, UCG and EFG), the sign-in page follows the Hotspot zone in Settings, Policy Engine, Zones: the network your guest WiFi uses must be in that zone, and nothing else should be. The picker tells you after applying if the zone needs attention, with the exact setting to change.
• The change applies gradually. Devices already online keep working until they reconnect; the sign-in page appears as each device rejoins.
• Your guest session length and speed limits are kept as configured.
• Available for self-hosted, API-key and Remote-Tunnel UniFi controllers (not UniFi Cloud connections, and not for controllers CaptiFi manages for you, where support makes the change).

Pre-authorized devices (printers, card machines, iPads)

Some devices cannot show a WiFi sign-in page: receipt printers, card machines, back-office iPads, music players and digital signage. On guest WiFi they would lose internet the next time they reconnect, because they can never complete the splash page. Pre-authorize them so they stay online without ever signing in.

On my.captifi.io, go to Locations, open the venue's connection status, and choose Pre-authorized devices. On app.captifi.io (classic) the same tool is the Pre-authorized devices action under My Sites.

For each device, enter its MAC address (and an optional label like "Front-desk printer"). You will find the MAC on a label on the device itself, or in your controller's client list. CaptiFi authorizes it on your UniFi controller straight away and then refreshes it automatically every night, so it keeps working across controller reboots without any further action.

• Removing a device from the list de-authorizes it on the controller, it will then need to sign in like a normal guest.
• If CaptiFi cannot reach your controller at that moment, the device is still saved and applied automatically within a day.
• Available for self-hosted, API-key and Remote-Tunnel UniFi controllers. For a device that has never connected, add it once it has joined the WiFi so the controller can identify it.

Staff SSID is still the tidiest option

If you have several headless devices, a separate password-protected staff SSID keeps them off the guest network entirely. Pre-authorized devices are the right choice when moving a device to another network is not practical.

Verify Controller Access

After setting up, verify it works:

1. Find your public IP at whatismyip.com
2. Test by visiting https://YOUR_PUBLIC_IP:443 (UDM) or https://YOUR_PUBLIC_IP:8443 (Cloud Key)
3. You should see the UniFi login page (you may need to accept a security warning)

If the page does not load and your gateway's WAN address is a private IP (starts with 10., 192.168., or 172.16. through 172.31.), you are behind double NAT. See Controller Behind Another Router (Double NAT / No Public IP) below.

TIP

Test from outside your network (e.g., from your mobile phone on 4G/5G, not WiFi) to confirm the rule is working correctly.

Controller Behind Another Router (Double NAT / No Public IP)

The methods above all rely on CaptiFi reaching your controller from the internet. If your UniFi console (UCG Ultra, UDM, Dream Router, or UniFi Express) sits behind another router, that inbound path does not exist. This is called double NAT, and it is fully supported: CaptiFi connects to your console through a secure Remote Tunnel instead, with zero changes to your router or ISP equipment.

Cloud Keys cannot run the Remote Tunnel

The tunnel needs WireGuard support in the console's operating system, which Cloud Key hardware (Gen2 and Gen2+) does not have. Cloud Key sites connect through port forwarding instead. If port forwarding is not possible at your site (CGNAT, or an upstream router you do not control), contact support and we will work out the best option with you.

You are likely behind double NAT if any of these apply:

• The UniFi app shows an "Upstream NAT detected on WAN1" banner
• Your gateway's WAN address is a private IP (starts with 10., 192.168., or 172.16. through 172.31.) rather than your public IP
• An ISP modem/router combo sits in front of your UniFi gateway (for example a Comcast Business gateway in default mode)
• Your ISP uses CGNAT (carrier-grade NAT), common on 4G/5G and some fibre connections
• Port forwarding is impossible, or you do not control the upstream router

How the Remote Tunnel works

The Remote Tunnel is a secure connection that your console dials out to CaptiFi. Because the connection is outbound only, it works behind any number of routers: no port forwarding, no bridge mode, no ISP changes. It also reconnects automatically after reboots, so setup is a one-time job.

1. Get your install command. Contact CaptiFi support (or your onboarding contact) and we will generate a one-line install command unique to your site.
2. Enable SSH on your console. In UniFi OS, go to Settings → Control Plane → Console, switch SSH on and set an SSH password (this is separate from your UniFi login).
3. Run the command. Connect to your console over SSH (ssh root@YOUR-CONSOLE-IP, using the SSH password) and paste the install command. The tunnel connects within about 30 seconds.
4. Create a local API key. In the UniFi Network app, go to Settings → Control Plane → Integrations → Create API Key. Copy the key when it is displayed (it is only shown once) and give it to CaptiFi support, or enter it in your CaptiFi dashboard. This requires UniFi Network 9.1.105 or newer.
5. Go live. Once the tunnel and API key are in place, the final step in your CaptiFi dashboard lists every WiFi network on your console. Pick the one the portal should gate (its broadcast name is kept automatically), or choose Create a new guest SSID and CaptiFi adds an open guest network across your access points. If you choose a name your console already broadcasts, CaptiFi gates that existing network rather than creating a duplicate. Prefer not to do this yourself? Give the API key to CaptiFi support and we will finish it for you. Either way, you can skip Step 2 and Step 3 of this guide and go straight to Step 4: Test.

If go-live reports a problem

The result message includes the controller's exact reply (for example api.err codes). Quote it when contacting support and we can usually resolve it in one step.

Picked the wrong network? You can swap it any time

Which SSID the portal gates is not locked in at go-live. See Changing which WiFi network the portal gates.

No username or password needed

Tunnel-connected consoles authenticate with the API key only. You do not need to create a local admin account or share any password with CaptiFi.

Check for headless devices before go-live

Devices that cannot display a web page (receipt printers, music players and iPads, card machines, digital signage screens) cannot complete a splash page, so they will lose internet access the next time they reconnect to the guest WiFi. Before the portal goes live, either:

• Move them to a separate private, password-protected staff SSID (recommended), or
• Add them under Pre-authorized devices so they stay online without signing in.

Good to know

• The portal applies gradually. Devices already connected keep working until they reconnect; the splash page appears as each device rejoins the network.
• The "Upstream NAT detected" warning is expected. With the Remote Tunnel in place, this banner in the UniFi app is harmless. No action is needed, and you should not enable bridge mode.
• iOS "Cannot Verify Server Identity" warning. If a guest sees this, their device is still behind the portal wall. They should open the WiFi sign-in page and complete it, or reconnect to the network. See Network Troubleshooting for details.

---

Step 2: Connect Controller to CaptiFi

Connected via the Remote Tunnel?

If your console connects through the Remote Tunnel (double NAT setups), CaptiFi completes this step and Step 3 for you. Skip ahead to Step 4: Test.

During the CaptiFi onboarding (or from your dashboard):

1. Log in to my.captifi.io
2. Go to My Locations → Add location (or, during onboarding, choose your hardware)
3. Choose Ubiquiti UniFi and pick your connection method:

Option A: API Key (Recommended — UniFi Network 9.1.105+)

This is the simplest and most secure method: no local admin account or password sharing.

1. In your UniFi controller, go to Settings → Control Plane → Integrations → Create API Key
2. Name the key (e.g. CaptiFi), set the role to Full Control, and create it
3. Copy the API key — it is only shown once
4. In CaptiFi, choose UniFi API Key
5. Enter your controller address (IP or hostname — CaptiFi adds https:// and finds the right port automatically) and paste the API key
6. Click Connect — CaptiFi will discover your sites automatically

Option B: Username & Password (Legacy)

This method requires a local account on your UniFi controller. Your normal Ubiquiti SSO (cloud) login will not work — CaptiFi connects directly to the controller's local API, which only accepts local credentials.

Accounts with MFA cannot be used

If the account you enter has multi-factor authentication (MFA/2FA) enforced — which is always the case for Ubiquiti cloud accounts, and can also apply to local accounts — CaptiFi will show "This Account Requires MFA" and the connection will fail. You have two options:

1. Use the API key method instead (recommended). API keys are not affected by MFA at all — see Option A above.
2. Create a dedicated local admin account without MFA as described below, and use that.

Create a Local Admin Account

Required Step

If you only have a Ubiquiti SSO login (the one you use at ui.com), you must create a local account first. Without it, CaptiFi cannot authenticate with your controller and you will see "Invalid credentials" errors.

On UniFi OS (UDM, UDM Pro, UDM SE):

1. Log in to your UniFi OS console (e.g., https://192.168.1.1)
2. Go to OS Settings (the gear icon in the top-left, outside of the Network app)
3. Select Admins & Users
4. Click Add Admin
5. Choose Local Access Only (not "Ubiquiti Account")
6. Fill in the details:
   • Username: Choose a username (e.g., captifi)
   • Password: Choose a strong password
   • Role: Administrator (full access is required for guest authorisation)
7. Click Add

On Cloud Key / Self-Hosted Controller:

1. Open the UniFi Network controller web interface
2. Go to Settings → Admins
3. Click Add New Admin
4. Select Local admin only (do NOT invite via Ubiquiti account)
5. Enter a username and password
6. Set Role to Administrator
7. Click Create

Best Practice

Create a dedicated account specifically for CaptiFi (e.g., username captifi). This makes it easy to identify CaptiFi's API access in your controller logs and allows you to revoke access without affecting your own admin login.

Connect to CaptiFi

1. In CaptiFi, choose UniFi Traditional (username & password)
2. Enter your controller address — CaptiFi tests reachability and detects the right port automatically
3. Enter the local account username and password you just created (tick the 2FA box if that account has two-factor enabled — you'll be asked for a 6-digit code)
4. Click Connect

After connecting:

1. CaptiFi will discover your sites and access points
2. Select which site(s) to manage
3. Import your sites

---

Step 3: Configure Captive Portal

This is the most critical step. You must configure your UniFi controller to redirect WiFi guests to CaptiFi's external portal.

3.1: Create or Edit a Guest WiFi Network

1. In your UniFi controller, go to Settings → WiFi
2. Either create a new network or edit your existing guest network
3. Set:
   • Name (SSID): Your guest WiFi name (e.g., "Free WiFi")
   • Security: Open (no password) — recommended for guest WiFi
   • Network: Guest network

3.2: Enable Hotspot Portal

1. Go to Settings → WiFi → Select your guest network
2. Scroll to Hotspot Portal and toggle it ON
3. Under Authentication, select External Portal Server

3.3: Configure External Portal Server

Enter these values exactly:

Setting	Value
IPv4 Address	46.62.168.7
Domain	site.app.captifi.io

3.4: Configure Pre-Authorization Access

Under Pre-Authorization Access (or Walled Garden), add:

Domain
site.app.captifi.io
*.captifi.io
app.captifi.io
fonts.googleapis.com
fonts.gstatic.com

3.5: Landing Page Settings

Under the Landing Page section, ensure ALL of these options are checked/enabled:

• Show Landing Page
• HTTPS Redirection Support
• Encrypted URL
• Secure Portal
• Domain — set to site.app.captifi.io

3.6: Apply Settings

Click Apply or Save to apply the configuration.

---

Step 4: Test

1. Connect a device (phone or laptop) to your guest WiFi
2. The CaptiFi splash page should appear automatically
3. If on mobile, you may need to open a browser and visit any HTTP site
4. Complete the login form
5. Check your CaptiFi dashboard — the guest should appear in your logs

---

Troubleshooting

Issue	Solution
Splash page not appearing	Verify Hotspot Portal is enabled and External Portal Server IP is exactly 46.62.168.7. On newer consoles also check the Hotspot zone (next two rows)
Guests get no sign-in page AND no internet on the guest network	On consoles with zone-based firewalling (new Dream Machines, UCG and EFG gateways), the sign-in page follows the Hotspot zone. Go to Settings, Policy Engine, Zones and make sure the network your guest WiFi uses is in the Hotspot zone. CaptiFi's go-live and WiFi network picker warn you when it is not
Sign-in page appears on a password-protected private network	The same zone setting, in reverse: that network is sitting in the Hotspot zone (or is set as a Guest network type). Move it back to the Internal zone / standard type. Every device on a Hotspot-zone network gets the sign-in page, WiFi password or not
"Portal unreachable" error	Check Pre-Authorization Access includes site.app.captifi.io
Guest can't get online after login	Verify the domain is set to site.app.captifi.io in Landing Page settings
Controller not connecting	Check your firewall rule or port forwarding is working (test from outside your network)
Cannot port forward / "Upstream NAT detected on WAN1"	Your console is behind another router (double NAT). CaptiFi supports this via the Remote Tunnel, see Controller Behind Another Router (Double NAT / No Public IP)
"Invalid credentials"	You must use a local account, not your Ubiquiti SSO (cloud) login. See Create a Local Admin Account above
"This Account Requires MFA"	The account has multi-factor authentication enforced, so a username and password alone can never sign in. Use the API key method (unaffected by MFA), or create a local admin account without MFA
API key not working	Ensure your controller runs UniFi Network 9.1.105 or newer, the key's role is Full Control, and the key has not expired
Sites not importing	Ensure your UniFi admin account has access to the site
HTTPS redirect issues	Enable "HTTPS Redirection Support" and "Secure Portal" in Landing Page settings
Firewall rule not working on UDM	Ensure Destination Zone is Gateway (not LAN), and the port group contains 80 and 443

Multiple Sites

If you have multiple UniFi sites:

• Each site can have its own splash page design
• Sites are automatically discovered when you connect your controller
• One API key covers all sites on the controller — you can create one CaptiFi location per UniFi site, all sharing the same connection
• During setup, make sure you choose a site from the dropdown on the "Set Up Your Venue" step before pressing Finish (with more than one site on the controller, CaptiFi cannot pick one for you)
• Manage per-site settings in My Locations on your CaptiFi dashboard (each additional CaptiFi location beyond the one included in your plan is £25/month)

Need Help?

UniFi setups can vary depending on your hardware and firmware version. If you're stuck:

• Email: hello@captifi.io
• Live Chat: Available on captifi.io