Skip to content
English
  • There are no suggestions because the search field is empty.

Ubiquiti Unifi API Configuration

Confirming Platform Details

Before proceeding with the configuration guide please complete the following steps so you have the required information to complete the guide.

  1. Login to your Marketing4WiFi dashboard
  2. Using the navigation panel to the left, select Settings ➡️ Customizations
    1. Splashpage hostname: Find your splashpage hostname and save it for use later in this guide.
    2. Platform Environment: Find your environment and then use the table below to determine your RADIUS Servers for use later in this guide.
      US-A US-B
      52.23.46.139 3.132.31.3
      52.207.192.243 3.18.137.68
      18.233.247.3 3.13.114.17

       


The following instructions outline how to setup a Ubiquiti UniFi network for the platform utilizing the API integration. This guide assumes that your Unifi controller is already operational and on a live network with adopted Access Points. Please make sure any firewall rules, web content filters, and other security measures have been configured to interface with the platform. 


Firewall Requirements

For the platform to communicate with your UniFi deployment, the UniFi Controller or UniFi Console must be reachable from the internet.

If your controller is hosted behind a firewall or NAT device, create the required firewall and/or port forwarding rules to allow inbound communication from the platform to the controller.

Allow traffic from the platform IP addresses associated with your environment to the following destination ports:

Deployment Type Protocol Port
UniFi Software Controller TCP 8443
UniFi Console (UDM, UDM Pro, Cloud Gateway, etc.) TCP 443

Important: Only allow access from the Smart WiFi Platform IP addresses listed in the Confirming Platform Details section above. Restricting access helps prevent unauthorized management access to your UniFi environment.


UniFi Account Requirements

Before proceeding, create or verify a local administrator account on the UniFi Controller or UniFi Console and confirm that:

  • The account is a local account, not a UI.com cloud account.
  • The account has Administrator permissions for the site being integrated.
  • The account can successfully log in directly to the UniFi Controller or UniFi Console.

You will use these credentials later when configuring the gateway in the Marketing4WiFi dashboard.

Important: The platform requires a local UniFi administrator account to communicate with the UniFi Controller API. UI.com cloud accounts are not supported for API authentication and will fail validation when testing the gateway connection.

Adding Gateways to your Hotspot

  1. Login to your GoZone Marketing4WiFi dashboard
  2. Using the navigation panel to the left, select Network ➡️ Gateways
  3. Click the Add Gateway option to the top right
    1. Select Hotspot: Select your desired hotspot
    2. Gateway Name: Enter any name for this gateway
    3. Gateway Type: Ubiquiti Unifi API
    4. MAC Address:  Enter the wireless MAC address of each Access Point that will broadcast the guest network. Every Access Point participating in the hotspot must be added to the gateway configuration. Additional AP MAC addresses can be added using the blue + button. 
    5. Unifi Connection Terminate:Enabling the Unifi Connection Terminate toggle will result in the platform polling the Unifi controller every 15 minutes and de-authorizing any active session if the device MAC is no longer associated to the wireless network with a reason for termination as Lost Carrier.
    6. Portal URL: Enter your Unifi controller public IP or valid hostname
    7. Username: Enter the username of a local site admin on the Unifi controller
    8. Password: Enter the password for the username of the local site admin on the Unifi controller entered above
    9. Click the ‘Test Unifi API Settings’ button to test the platform communication to your Unifi controller.
    1. Select the correct Site after the field populates from the successful use of the Test Unifi API Settings button.
  1. Press Submit
  2. This completes the Gateway creation portion of this guide

Unifi network configuration

  1. Login to your Unifi controller and select the correct site
  2. On the menu to the left, click the Settings option
  3. On the WiFi Tab, click Create New or Edit your existing Guest WiFi
    • Hotspot Portal: Checked
    • Set all other options to best practices
    • Press Add WiFi Network (or Apply Changes)
  4. On the menu to the left, click the Hotspot Manager option
  5. Click the Landing Page tab at the top of the page
  6. Using the menu panel to the right, on the Branding tab configure with
    • Success Landing Page: Select Custom URL and use the value you are provided
  7. Using the menu panel to the right, on the Authentication tab configure with
    • External Portal Server: Enabled
    • External Portal: 8.8.8.8
       Note: The External Portal value is only used to satisfy the UniFi configuration requirement. Authentication is handled by the Marketing4WiFi platform through the API integration. 
  8. Using the menu panel to the right, on the Settings tab configure with
    • Show Landing Page: Checked
    • HTTPS Redirection Support: Unchecked
    • Encrypted URL: Checked
    • Secure Portal: Checked
    • Domain: You will be provided this value
    • Pre-Authorization Allowances: Add the value you used for the Domain as well the platfrom Default walled garden entries.
  9. Press Save

Hardware dependent features

  • This integration supports the platform’s Session Profile values for Download/Upload speed. This means bandwidth throttling is set by the platform when a guest connects to a hotspot using any login method, including Guest Plans and Ad-Based.
  • This integration supports Presence/Proximity data. This means Presence Campaigns can be configured for a hotspot utilizing this hardware.
  • This integration supports the SecurePass™ module. This means a hotspot utilizing this hardware can provide dynamically generated wifi passwords to guests who purchase a Guest Plan.
  • This integration utilizes an HTTPs post to initiate authentication by default. This means devices interacting with the splash page on a full feature browser should not be displayed an HTTP Browser Post warning after clicking the connect button.

Troubleshooting Tips

  1. If devices present an certificate error please ensure https redirection is disabled.
  2. If a hotspot deactivated message is presented please ensure all the AP MACs have been added as gateways to the correct hotspot.
  3. If devices are redirected to the splash page URL but the page fails to load please ensure the Allowed Authorization Access list has been properly configured.
  4. If the API Test Fails, Verify the following:

    1. The Portal URL is publicly accessible.
    2. The correct port is reachable (8443 for Software Controllers or 443 for UniFi Consoles).
    3. A local UniFi administrator account is being used.
    4. Firewall and NAT rules have been configured correctly.
    5. No security appliance is blocking communication from the platform IP addresses.
    6. The correct username and password have been entered.

LIMITED HARDWARE SUPPORT: Hardware manufacturers frequently make changes to firmware, controllers and GUI’s. The information below may be out of date or images may be different and is to be used as a general reference guide. We do offer additional limited support to help with trouble-shooting and we highly recommend that you have a hardware support agreement and/or access to a hardware support engineering representative from the manufacturer.

This equipment has been integrated and tested in our labs with the Marketing4WiFi platform using the firmware versions below.

  • UniFi CloudKey Version 7.2.92-18687-1 Firmware 1.1.19
  • Unifi UDM SE OS Version 3.2.12
  • Unifi Network Server Network 8.1.113
  • Unifi U6 Lite Version 6.6.55