Troubleshooting

UniFi authorize guest returns 403

A 403 from UniFi can come from three different places: the login, the authorize call after a good login, or something standing in front of the controller. Portal Health and Test Connection tell you which.

Why does UniFi return 403 when authorizing a guest?

If the login returns 403, the account is wrong: a cloud account, two factor, or a bad password. If the login works and the authorize call returns 401 or 403, the CSRF token is missing or the account cannot manage that site. A proxy or access gate in front of the controller can also answer 403 itself.

Causes, in the order to check them

1. The login is rejectedUniFi

Cause

Cloud accounts, accounts with two factor, and wrong passwords are refused at /api/auth/login (UniFi OS) or /api/login (self hosted). Portal Health shows auth with “login rejected (HTTP 403)”. These are not retried.

Check

Test Connection on the location reports the same rejection.

Fix

Create a local admin with Network access and no two factor, save it, and test again.

2. The CSRF token never arrivedUniFi

Cause

UniFi OS rejects state changing calls without a CSRF token. Some proxies strip the x-csrf-token header. The integration falls back to the token inside the TOKEN cookie; if a proxy also drops cookies, the authorize call fails.

Check

Fix

Pass headers and cookies through the proxy unchanged, or connect through a tunnel that does.

3. The account cannot manage that siteUniFi

Cause

A read only role, or an account without access to the venue’s site, can log in but cannot authorize guests there.

Check

Test Connection succeeds but the venue’s site is missing from the returned list.

Fix

Give the account Network access to that site, then pick the site again from the list.

4. Something in front of the controller answeredOmada and UniFi

Cause

An access gate or a firewall rule on the hostname can answer with its own 403 or a login page before the request reaches UniFi. HTTP 407 specifically comes from the optional egress proxy, not the controller.

Check

Open the controller address from a phone on mobile data. If you see a login page that is not UniFi’s, this is it.

Fix

Exempt the API paths from the gate, or publish a second hostname for the integration with the gate off and restrict it another way.

5. Port and console type mismatchUniFi

Cause

A self hosted controller on :8443 addressed without its port, or a proxy that confuses console detection, can send the login to the wrong endpoint.

Check

Test Connection reports an unexpected console type.

Fix

Include :8443 for self hosted controllers, or set Console Type explicitly to UniFi OS or Legacy.

Reference

Where a UniFi 401 or 403 comes from
Seen in	Likely source	First check
Test Connection and Portal Health, kind auth	Login rejected	Local account, no two factor
Portal Health only, kind controller	Authorize call rejected	CSRF passthrough, site access
A non UniFi login page on the hostname	Access gate or firewall	Exempt the API paths
HTTP 407	Egress proxy credentials	Platform configuration

Questions

Does the integration retry a 403?

A rejected login is not retried, because a wrong password will not fix itself. An authorize call that reports LoginRequired or Unauthorized is retried once with a fresh login.

Is the self signed certificate the cause?

No. The UniFi integration accepts self signed certificates by default, and a certificate failure is reported as ssl, not 403.

Keep reading

UniFi setup hub UDM Pro setup Portal loads but the WiFi never unlocks Captive portal not showing on iPhone All troubleshooting guides

Error kinds and codes on this page are the ones the VoqadoWiFi integration records, checked against the code on 7 October 2026.

See every authorization attempt

Portal Health in the free dashboard shows each guest login with its error kind and code. One location and 25 guest logins a month, no card.