UniFi Integration: Best Practices & Common Questions

Overview

The UniFi Integration connects Purple directly to your UniFi Network Controller using a modern API login method, rather than relying on complex background authentication channels like RADIUS. Think of it as Purple securely logging into your controller as a dedicated automated user to quickly approve your guests when they fill out your splash page. Because this setup works like a direct web connection, fixing issues usually comes down to checking web addresses, firewalls, and account permissions.

Prerequisites & Best Practices

Before configuring your integration, ensure your UniFi system is prepared to communicate smoothly with Purple's secure cloud servers.

1. Create a Dedicated UniFi Admin Account

For the automation to work without getting blocked, you must create a dedicated account directly inside your UniFi Controller. For security and reliability, configure it exactly like this:

• Local Account Only: The account must be built locally on the controller, not a Ubiquiti cloud account (ui.com email login). If your interface forces an email setup, switch your UniFi controller to Legacy UI mode under settings to create a standard local username and password instantly.
• Full Administrator Rights: The user must have administrator/write privileges. A "Read-Only" profile cannot execute guest authorizations.
• Turn Off 2FA: Two-Factor Authentication (2FA) must be completely disabled for this specific user, as interactive challenges block automated backend queries.
• Keep Passwords Stable: Ensure the "Require user to change password" check box is completely unchecked.

Important Update for Modern Controllers:

• For UniFi OS 8.6.9+ (Hardware Consoles): Navigate directly to your primary UniFi OS Dashboard (the main system settings, not just the Network App), go to Admins & Users, and create a new profile. Set the Account Type explicitly to Local Access Only and assign the Site Admin role so our API can authenticate properly.
• For New Self-Hosted Environments (UniFi OS Server): Make sure your dedicated API account is created at the root OS container layer so the internal Nginx front-end proxy can validate the credentials before routing them to the Network application.

2. Register Your Hardware Correctly in Purple

When pairing your network inside the Purple portal, do not select individual access point (UAP) model numbers. Instead, select the orchestration platform that manages them:

• Choose UniFi Network (Current Default) for all new deployments. This includes physical hardware consoles (UDM, UDW, UDR, CloudKey Gen2), high-end firewalls (Enterprise Firewall Gateway / UDM Fortress), and any self-hosted Ubuntu/Debian servers that have upgraded to modern UniFi OS Server (v5.0.6 / Network App 10.x and higher).
• Choose UniFi Network Controller (Legacy) only if you are running an older, unupgraded instance of the standalone software controller application on an internal computer or legacy cloud host.

3. Open Network & Firewall Paths

Because Purple's servers make a direct connection to your controller, your network needs a clear path to receive these requests:

• Static Public IP or FQDN: If your controller is hosted inside your local network, your main internet connection must use a permanent, static public IP or a stable web address (FQDN) so Purple always knows where to find it.
• Configure Port Forwarding: Ensure your router or firewall redirects incoming traffic to your controller's internal IP address using the correct port numbers:
  • Port 11443 (New Default): Required if your self-hosted server has been upgraded to the modern UniFi OS Server architecture.
  • Port 8443 (Legacy Default): Only used if your server is running older, standalone versions of the UniFi Network Application.
  • Port 443: Used if your system is running on official Ubiquiti hardware consoles (UDM, UDW, UDR, or CloudKey Gen2).
• Whitelist Purple's IP Addresses: If you have an active security firewall, configure it to allow inbound traffic from Purple's regional cloud delivery nodes:
  • Region 1: Contact Support
  • Region 2: Contact Support
  • Region 3: Contact Support

Common Questions & Troubleshooting

• Why do my guests experience long delays or get stuck on a blank screen after submitting the WiFi form?
  This happens when your network's guest rules accidentally block the hidden web traffic required to finish the login process. Even though the guest successfully filled out the form, the network won't let them reach the final redirect page.
  
  The Fix: Open your UniFi Controller, navigate to Access Control, and explicitly declare all essential target routing paths within your Pre-Auth ACL (Access Control List) or Post-Authorization settings.
• Why is the payment screen failing or freezing when guests try to buy WiFi access?
  UniFi's security firewall strictly blocks all internet access until a guest is fully logged in. To let guests pay via Stripe or PayPal, you must create a firewall exception.
  
  The Critical Limitation: UniFi platforms (including enterprise security gateways like the UXG Enterprise or EFG) do not support true wildcard domain matching (using *) in their firewall rules. If your payment gateway relies on dynamic subdomains, UniFi will block the traffic and cause SSL inspection errors. You must manually look up the specific, numerical public destination server IP addresses for your payment provider and add those exact numbers directly into UniFi's Pre-auth Access Control List (ACL) parameters.
• My server recently updated, and now guests get stuck or see a "404 Not Found" error loop. How do I fix this?
  This happens when an existing self-hosted software server upgrades to the modern UniFi OS Server framework.
  
  The Cause: Legacy setups used the web path /api/login on Port 8443. The modern UniFi OS architecture changes the required URL login path to /api/auth/login and shifts the default web port to TCP port 11443. If your Purple dashboard is still set to the legacy hardware type, it queries the wrong path, resulting in a fatal 404 Not Found response.
  
  The Fix: Log into the Purple portal, go to your Venue Settings, and change your hardware type from the old legacy selection to the modern UniFi Network option. Ensure you update your router's port forwarding rules to allow traffic over external Port 11443, and add the port reference suffix (:11443) right next to your controller IP address in Purple.
• I am seeing a "Connection Timed Out" or reachability warning in my portal dashboard. What's wrong?
  This means Purple's cloud platform is trying to reach your network, but your UniFi Controller isn't answering the request.
  
  Check your addresses: Verify that your controller's public IP address or web address is typed perfectly in your Purple Venue Settings.
  Verify your IP status: Make sure your internet connection uses a permanent, static public IP address if the controller is hosted inside your business's network.
  Check Port Forwarding: Ensure your router's port forwarding rules are active and sending traffic to your controller's internal IP using Port 11443 or Port 443 depending on your setup.
  Check your Firewall: Make sure your security firewall whitelists Purple's regional cloud IP addresses.
• Why am I getting a generic login failure or mismatch error during setup?
  If your username and password are correct but the portal refuses to connect, there is a data structure mismatch between Purple and your UniFi system.
  
  The Fix: This almost always happens when the hardware type selected in the Purple portal doesn't match your software version, which forces the system onto the wrong port and login path. Select UniFi Network for all modern deployments - physical hardware consoles (UDM, UDW, UDR, CloudKey Gen2), enterprise firewalls, and self-hosted servers upgraded to UniFi OS Server. Only select UniFi Network Controller (Legacy) if you are running an older, unupgraded instance of the standalone software controller.
• The credentials I entered are correct, but the integration still fails to authorize guests. Why?
  Your login details match perfectly, but the specific account you created for Purple doesn't have the internal authority required to modify network states. While the login itself succeeds, Purple needs to be able to actively "write" permission data to approve a guest on your network.
  
  The Fix: Log into your UniFi Controller, look at your administrator list, and promote the Purple API account's role to a full Administrator with write privileges.
• The setup is failing and mentioning a security challenge or authentication block. How do I bypass this?
  This indicates that Two-Factor Authentication (2FA) or a mandatory password change prompt is active on the account Purple is trying to use. Because Purple is an automated cloud system, it cannot read a temporary security text or click an interactive link.
  
  The Fix: Convert the profile or create a new profile that is a dedicated local administrator account with 2FA completely turned off. Ensure the "Require user to change password" box is completely unchecked.
• I host my controller on unifi-hosting.ui.com and the setup cannot find my site. How do I fix it?
  If you use Ubiquiti's official managed cloud hosting instances, the system handles data ports differently than a traditional computer-hosted software controller. Because it is built on UniFi OS to run multiple applications simultaneously, the legacy classification forces an incorrect port path.
  
  The Fix: Go to your Purple settings and change your WiFi Hardware Type to UniFi Network. This forces Purple to communicate using the correct UniFi OS port and login path instead of the legacy software port 8443.