TP-Link Omada, cloud hosted

Omada Cloud-Based Controller captive portal setup

With the cloud-based controller TP-Link hosts the brain for you, so there is no box to expose and no port to open. The work moves to two identifiers, the Controller ID and the Site ID, and to knowing which cloud hostname your controller lives on.

Print my Omada settings All Omada controllers

How do I set up an external portal on the Omada cloud controller?

Sign in at omada.tplinkcloud.com, open your site, go to Settings, Authentication, Portal, choose External Portal Server and paste your VoqadoWiFi portal URL. Allow www.voqadowifi.com and voqadowifi.com before authentication. In the dashboard save your cloud controller address, the Site ID and the Controller ID, which appears as omadacId in the redirect.

At a glance

Where you sign in: omada.tplinkcloud.com
Portal setting: Settings, Authentication, Portal, External Portal Server
Inbound port needed: None
Identifiers the dashboard needs: Site ID and Controller ID (omadacId)
Where the token goes: TP-Link’s cloud API host, /<omadacId>/portal/auth
Retried automatically: Codes -41009 and -41501

Checked against the VoqadoWiFi integration code on 7 October 2026. Controller menu labels move between firmware releases; the setting names above are the ones the setup wizard prints.

Step by step

Open the site in the cloud controller
Sign in at omada.tplinkcloud.com and open the site that carries the guest SSID.
Set the guest portal to External Portal Server
Go to Settings, Authentication, Portal, edit the portal bound to the guest SSID, and choose External Portal Server.
Paste the portal URL exactly as the dashboard prints it
Enter https://www.voqadowifi.com/portal/your-venue-slug with no trailing slash and no question mark of your own. Omada appends clientMac, apMac, ssidName, radioId and a one time token to the URL, and a second query string breaks that hand off.
Allow the portal domain before authentication
Add www.voqadowifi.com and voqadowifi.com to Pre-Authentication Access on the same portal. The full list, with the reason for each line, is on the walled garden page.
Copy the Controller ID from a real redirect
Join the guest SSID on a phone. The portal address the phone opens carries omadacId= followed by a long identifier. That is the Controller ID. Save it in the dashboard so authorization still works if a redirect ever arrives without it.
Save the controller details in the dashboard
Enter your cloud controller’s tplinkcloud.com address as the Omada Controller URL, plus the Site ID and Controller ID, then run a test login and check Portal Health.

What breaks on this controller

The wrong cloud hostname

The integration sends the token to the API host named in your controller address when it is a tplinkcloud.com host, and to the US East API host otherwise. A controller hosted in another region needs its own API hostname in the dashboard.

The Essentials CDN hostname

Omada Essentials controllers have a browser hostname that sits behind a cache which refuses the POST the token needs. The integration rewrites that hostname to the matching api- host automatically, so paste the address you see in the browser and let it correct it.

Transient cloud errors

Codes -41009 and -41501 mean the cloud was briefly unstable. The integration retries them before giving up. If you see them in Portal Health once in a while, nothing is misconfigured.

A missing Controller ID

Without omadacId the token path cannot be built for the cloud, and the credential fallbacks cannot run either. Portal Health shows auth with “Controller ID missing”. Save the ID from a real redirect.

What happens after the guest presses connect

VoqadoWiFi first returns Omada’s one time token to the cloud API host at /<omadacId>/portal/auth, with the device MAC, access point MAC, SSID, radio and the session length. That is the standard external portal hand off and it needs no stored password.

If the controller rejects the token and the location has Omada OpenAPI client credentials or a hotspot operator account on file, the integration tries those next. Code -41010 from the OpenAPI method means the device is not waiting in the portal state for that method, and the integration moves on to the operator method.

Codes -1 and -3 mean the device is already authorized, and the integration treats them as success, so a guest who was already online is not shown a failure.

Questions

Do I need to open any port for the cloud controller?

No. The redirect comes from your access points, and the authorization goes to TP-Link’s cloud API, which is on the internet already.

Where do I find the Controller ID?

In the address of any portal redirect, after omadacId=. Join the guest network on a phone and read it from the portal URL.

Does the cloud controller cost money?

TP-Link licenses the cloud-based controller per managed device. Check TP-Link’s current terms; the VoqadoWiFi side is free on the Starter plan.

Why do I occasionally see -41009 in Portal Health?

It is a transient cloud error. The integration retries it automatically, and an occasional entry is not a configuration problem.

Deeper reading

Longer articles from the blog that cover this controller. Where an article and this page disagree, this page is the one checked against the current integration.

Omada cloud vs local controller. Rent versus buy, honestly.
How the captive portal mini browser behaves

Keep reading

Omada setup hub Omada authorization error codes OC200 and OC300 setup Walled garden domains

Sources: lib/omada/api.ts (buildAuthUrl cloud branch, Methods A, B and C, error codes) and the setup wizard, read on the date above. TP-Link and Omada are trademarks of TP-Link Technologies. VoqadoWiFi is not affiliated with or endorsed by either vendor.

Run your Omada portal free

One location and 25 guest logins a month on the Starter plan, no card. The dashboard prints the finished portal URL for this controller.