Captive
Sign inStart free trial

Quickstart

From a fresh UniFi console to a live email-capturing portal. You'll need admin access to a UniFi gateway (Dream Machine, Cloud Gateway, or any console running the Network application) and a guest WiFi network.

1. Get a UniFi API key

Captive connects to your console through the UniFi cloud — the same outbound tunnel that powers unifi.ui.com. Nothing connects inbound to your network, so no port forwarding, static IP, or firewall changes are needed.

  1. Make sure the console has Remote Access (Ubiquiti cloud) enabled and is running UniFi OS 5.0.3 or newer.
  2. Sign in at unifi.ui.com and create an API key (unifi.ui.com → API).

Prefer not to link the console to a Ubiquiti account? Use the direct connection below instead.

2. Point a portal hostname at Captive

Each site gets a portal hostname guests are redirected to. Create a DNS record (e.g. cabin.portal.yourdomain.com) pointing at Captive, or use the app's own hostname if you run a single site.

3. Add the site

Dashboard → Add site: pick UniFi cloud, paste the API key, click Find consoles and choose the console at this property, then set the portal hostname. Captive tests the connection before saving (or tick "save without testing" and fix connectivity later).

4. Configure the hotspot portal

The portal settings live in the gateway's hotspot configuration. Set them in the UniFi console once: Settings → Hotspot Portal → Authentication → External Portal Server, enter your portal hostname, and add the portal's addresses to the pre-authorization allowances (look up the hostname's IP addresses and allow each one's /24) so guests can reach the sign-in page before they're authorized.

Sites using the direct connection can instead click Auto-configure portal on the site page and Captive writes these settings for you: external-portal mode, your portal hostname, the pre-auth walled garden, and the guest session length.

Heads up: the hotspot portal is per UniFi site, not per SSID. Every WLAN flagged as a guest network cuts over to Captive at once. Devices authorized under a previous portal stay online until their session expires.

5. Flag your guest WLAN(s)

On the site page, click Show WLANs and flag the SSID(s) your guests use as guest networks. Non-guest WLANs (your own devices) are untouched.

6. Test it

Join the guest SSID with a phone. The portal should appear; submit an email and you should be online. The signup appears under Dashboard → Emails with authorized: true. If something misbehaves, see Troubleshooting.

You can also preview any portal without joining WiFi: /guest/s/default/?site=<your-site-slug>&id=aa:bb:cc:dd:ee:ff&ssid=TestWiFi.

Alternative: direct connection

If you'd rather Captive sign into the console directly (no Ubiquiti cloud involved), the console must be reachable from Captive's servers over HTTPS — port forward TCP 443 to the gateway's management IP, or use a VPN / Tailscale address. Inbound reachability varies by ISP (CGNAT, dynamic IPs, and upstream filtering all break it), which is why the cloud connection is the default.

  1. On the console: UniFi OS → Admins & Users → Add Admin.
  2. Choose Restrict to local access only and set a username + password.
  3. Give it Network app permissions (Full Management).
  4. Don't enable two-factor on this account — Captive can't answer 2FA prompts.

Pick Direct connection in the add-site form and enter the controller URL (usually your public IP — the wizard defaults to the IP you're visiting from) and the local admin credentials. The console's self-signed TLS certificate is accepted for controller API calls only.