What Omada SDN Provides
TP-Link Omada SDN (Software Defined Networking) is a centralised management platform for TP-Link Omada-series access points, switches, and gateways. From a WiFi marketing perspective, its core value is threefold:
Centralised controller: All access points — whether in one venue or across 50 — are managed from a single interface. SSID configuration, portal settings, and firmware updates are pushed from the controller rather than configured individually on each device.
Site management: Omada organises infrastructure into "sites," where each site typically corresponds to a physical location. A multi-location operator can manage all locations from one Omada controller while maintaining independent SSID, VLAN, and portal configurations per site.
AP discovery and zero-touch provisioning: New Omada APs added to a network are automatically discovered by the controller via Omada's discovery protocol. This makes hardware additions to existing deployments straightforward — install the AP on the correct network segment and it appears in the controller within minutes, ready for configuration.
For VoqadoWiFi integration, Omada's external portal server feature is the critical capability. This allows Omada to redirect unauthenticated guests to a URL of your choosing — the VoqadoWiFi portal — before granting internet access.
How the Portal Auth Handshake Works
Understanding the authentication handshake is essential for troubleshooting and for configuring the integration correctly. The sequence is:
1. Guest associates with SSID. The device connects to your guest WiFi network at the 802.11 layer.
2. Omada assigns an IP via DHCP. The guest device receives a local IP address, typically in the 192.168.x.x range for a guest VLAN.
3. Omada intercepts HTTP requests. When the guest device attempts to load any HTTP URL (or follows a standard captive portal detection request), Omada redirects the browser to the External Portal Server URL configured in your Omada portal settings.
4. Browser loads the VoqadoWiFi portal. The redirect URL includes several query parameters appended by Omada: the client MAC address, the AP MAC address, the SSID name, and a time-stamped authentication token (varies by Omada firmware version; current format uses `client_mac`, `ap_mac`, `ssid`, `login_url`, and `continue_url`).
5. Guest completes the opt-in form. VoqadoWiFi records the submission, validates consent, and syncs to your email platform.
6. VoqadoWiFi calls Omada's authentication API. After form completion, VoqadoWiFi sends an authentication request to the Omada controller's API endpoint, identifying the guest MAC address as authorised. This can use either the Omada Software Controller's local API (for self-hosted controllers) or the Omada Cloud API (for OC200/OC300 hardware controllers or Omada Cloud).
7. Omada grants internet access. On receiving the API authentication confirmation, Omada transitions the client from the "unauthenticated" state to "authenticated" and removes the traffic redirect. The guest's browser follows the `continue_url` parameter to a post-connection landing page.
The entire handshake, from portal load to internet access, takes 2–4 seconds when all components are configured correctly and the controller API is responsive.
Controller URL Formats
The API endpoint format differs between controller types:
Omada Software Controller (self-hosted on Windows/Linux):
https://[controller-ip]:[port]/[site-name]/api/v2/hotspot/extPortal/auth
Default port is 8043. The site name is URL-encoded (spaces replaced with %20 or +). Example:
https://192.168.1.100:8043/Main%20Site/api/v2/hotspot/extPortal/auth
Omada Hardware Controller (OC200 / OC300): Same format as Software Controller but accessed at the controller's LAN IP. These devices run the same controller software, so the API path is identical.
Omada Cloud (cloud-managed, no local controller):
https://api.omada.com/openapi/v1/hotspot/extPortal/auth Cloud API requires an API key generated from the Omada Cloud portal under Site Settings > API. Cloud API calls also require the site ID (a UUID) as a path or query parameter.
In VoqadoWiFi's Omada integration settings, you select the controller type (Software/Hardware or Cloud), enter the controller URL or domain, provide credentials (operator-level Omada account), and specify the site name. VoqadoWiFi handles the API call construction internally.
Common Setup Mistakes
Mistake 1: Portal URL missing the HTTPS scheme. Omada requires the External Portal Server URL to use HTTPS. An HTTP URL will fail silently on some firmware versions and redirect to a browser warning on others. VoqadoWiFi portal URLs are always HTTPS; ensure you copy the full URL including the scheme.
Mistake 2: Guest VLAN cannot reach the controller API. When guest traffic is isolated in a VLAN (which it should be, for security), the VLAN routing configuration must allow outbound traffic to the Omada controller's API port. A common misconfiguration is a guest VLAN firewall rule that blocks all non-internet traffic — this prevents VoqadoWiFi from calling the Omada authentication endpoint. The Omada controller IP should be whitelisted for outbound TCP on port 8043 (or your configured port) from the guest VLAN.
Mistake 3: Incorrect site name. The Omada site name in VoqadoWiFi must exactly match the site name in your Omada controller, including capitalisation and spaces. A mismatch produces an "invalid site" API error. Check the site name in Omada under Settings > Site.
Mistake 4: Using an admin account instead of an operator account. Omada's API authentication uses role-based access control. The Omada SDK documentation recommends using an Operator-level account (not the global admin) for external portal API calls, as this limits the scope of the credentials if they were ever compromised. Create a dedicated VoqadoWiFi operator account in Omada under Admins & Users.
Mistake 5: Portal not configured as "External Portal" in Omada. In the Omada wireless settings, navigate to your SSID > Portal. The portal type must be set to "External Web Portal" (not "Simple Password" or "Omada Portal"). Without this setting, Omada will not redirect guests to the VoqadoWiFi URL.
Cloud vs Hardware Controller: Which to Choose
For most venue operators, the choice between Omada Cloud management and a hardware controller (OC200/OC300) comes down to scale and reliability requirements:
Omada Cloud: No local hardware required. Controller is managed by TP-Link's infrastructure. Suitable for venues with fewer than 15 APs per site and internet connectivity that is reliable enough that a controller outage (cloud depends on internet) would not be operationally significant. Monthly subscription cost after the first year.
OC200 (hardware controller, up to 100 devices): Local device installed on the network. Functions without internet access (useful for internet outages — local authentication still works). One-time hardware cost (approximately £100–£150). Recommended for venues where WiFi portal authentication must remain functional during internet outages.
OC300 (hardware controller, up to 500 devices): Same as OC200 but higher capacity. Suited for large venues, hotel complexes, or multi-building deployments.
Software Controller: Free, self-hosted on a Windows or Linux machine. Suitable for technically capable operators who want maximum control and no hardware cost. Requires the host machine to be running continuously.
For VoqadoWiFi integration: all four controller types are supported. The OC200 is the recommended choice for single-venue deployments, given its combination of local reliability, managed hardware, and straightforward API access.
Site Segmentation for Multi-Location
For operators running VoqadoWiFi across multiple locations with a single Omada controller, site segmentation ensures that guest data from each location is correctly attributed and that portal customisation can differ between locations.
In VoqadoWiFi, each location is configured as a separate "venue" with its own portal, branding, contact list, and Mailchimp audience. In Omada, each location corresponds to a separate "site." The VoqadoWiFi integration maps each VoqadoWiFi venue to a specific Omada site.
When a guest connects at Location A, the redirect goes to Location A's VoqadoWiFi portal. The authentication API call specifies Location A's Omada site. Guest data is tagged to Location A in VoqadoWiFi's analytics. Location B's portal, branding, and audience are entirely independent.
This segmentation also means that marketing consent captured at Location A is explicitly attributed to Location A, which is important for GDPR compliance if the locations operate as separate legal entities.
Troubleshooting Connection Timeouts
If guests are completing the portal form but not receiving internet access (the browser stays on the portal page or shows a timeout):
1. Check the Omada API response in VoqadoWiFi under Integrations > Omada > Logs. A `200 OK` response indicates successful authentication. A `401` indicates credential failure. A `404` indicates an incorrect site name or API path.
2. Verify controller reachability from the VoqadoWiFi server. VoqadoWiFi's servers must be able to reach your Omada controller's API port. If your Omada controller is behind a NAT on your venue's network (not exposed to the internet), you will need to configure port forwarding or use the Omada Cloud API instead.
3. Check Omada firmware version. The authentication API parameters changed in Omada firmware 5.x. VoqadoWiFi supports both the 4.x and 5.x API formats; ensure your firmware version matches the API format selected in VoqadoWiFi's integration settings.
4. Test with a known-good device. Some older Android devices do not follow the captive portal detection redirect correctly. Test with a current iOS or Android 12+ device before investigating infrastructure issues.
5. Review guest VLAN firewall rules for any rules that might block the Omada controller authentication callback to the guest device after authentication. The Omada controller sends an RADIUS-equivalent signal to the AP; this is an internal LAN communication and should not traverse the guest VLAN firewall, but misconfigured rules can interfere.
The VoqadoWiFi support team is available via in-app chat and can review your integration logs directly. For complex multi-site deployments, a screen-share session with our integrations team is included in all plans and resolves the majority of issues within 30 minutes.