How to Create an Omada Guest Wi-Fi Network with the API

A separate guest Wi-Fi network is one of the most useful upgrades for a home lab or small office. Visitors get internet access, while the devices you trust stay out of reach.

This guide shows how to create an Omada guest SSID with the controller API instead of clicking through the web interface. The examples are deliberately generic: replace the placeholders with values from your own controller, and never publish real credentials or controller addresses.

What this setup does

• Creates a new WPA-protected SSID.
• Enables Omada Guest Network isolation.
• Prevents guests from communicating with one another.
• Leaves VLAN tagging disabled, so no switch or router trunk change is required.
• Applies the SSID to the WLAN group used by the managed access points.

This is an AP/controller-level guest boundary. It is a useful low-risk option when the access points are connected through an unmanaged switch, but it is not the same as a routed firewall VLAN. A VLAN remains the better long-term design when the switching and gateway path support it.

The API choice

Omada has an official Open API on supported controller versions, and the web application also uses controller endpoints under /api/v2. The examples below use the latter because it is available on older software-controller installations and maps closely to the settings exposed by the UI.

That convenience comes with a trade-off: the UI-facing API is not a stable public contract. Endpoint names and payload fields can change between controller releases. Pin your controller version, test against a lab site first, and prefer the official Open API for new integrations when its coverage is sufficient.

1. Log in without hard-coding secrets

Use an environment variable, secret store, or CI secret for the controller credentials. Do not place a real password in a script, shell history, screenshot, blog post, or Git repository.

export OMADA_URL="https://controller.example.invalid:8043"
export OMADA_USER="api-admin@example.invalid"
export OMADA_PASSWORD="use-a-secret-store"

LOGIN=$(curl -sk -c omada.cookies \
  -H 'Content-Type: application/json' \
  -d "{\"username\":\"$OMADA_USER\",\"password\":\"$OMADA_PASSWORD\"}" \
  "$OMADA_URL/api/v2/login")

TOKEN=$(printf '%s' "$LOGIN" | jq -r '.result.token')
test "$TOKEN" != "null"

The controller returns a short-lived token. Send it as the Csrf-Token header on subsequent requests and keep the session cookie returned by the login call.

2. Discover the controller and site IDs

OMADAC_ID=$(curl -sk "$OMADA_URL/api/v2/anon/info" \
  | jq -r '.result.omadacId')

SITES=$(curl -sk -b omada.cookies \
  -H "Csrf-Token: $TOKEN" \
  "$OMADA_URL/$OMADAC_ID/api/v2/sites?currentPage=1&currentPageSize=100")

SITE_ID=$(printf '%s' "$SITES" | jq -r '.result.data[] | select(.name == "home") | .id')

WLAN_GROUPS=$(curl -sk -b omada.cookies \
  -H "Csrf-Token: $TOKEN" \
  "$OMADA_URL/$OMADAC_ID/api/v2/sites/$SITE_ID/setting/wlans?currentPage=1&currentPageSize=100")

WLAN_ID=$(printf '%s' "$WLAN_GROUPS" | jq -r '.result.data[0].id')

Do not assume that the first site or WLAN group is the correct one in a multi-site controller. Select them by a known name, then check the result before making a write request.

3. Create the guest SSID

The important fields are the SSID name, the security settings, guestNetEnable, and vlanEnable: false. The last setting is intentional: this example avoids changing the physical network path.

cat > guest-ssid.json <<'JSON'
{
  "name": "ExampleGuest",
  "band": 7,
  "type": 0,
  "guestNetEnable": true,
  "security": 3,
  "broadcast": true,
  "vlanEnable": false,
  "portalEnable": false,
  "accessEnable": false,
  "pskSetting": {
    "versionPsk": 4,
    "encryptionPsk": 3,
    "gikRekeyPskEnable": false,
    "securityKey": "replace-with-a-new-password"
  },
  "wlanScheduleEnable": false,
  "macFilterEnable": false,
  "enable11r": false,
  "pmfMode": 2,
  "multiCastSetting": {
    "multiCastEnable": true,
    "channelUtil": 100,
    "arpCastEnable": true,
    "ipv6CastEnable": true,
    "filterEnable": false
  },
  "greEnable": false,
  "dhcpOption82": { "dhcpEnable": false },
  "deviceType": 3,
  "vlanSetting": { "mode": 0, "customConfig": {} },
  "wpaPsk": [2, 3],
  "prohibitWifiShare": true,
  "mloEnable": false
}
JSON

curl -sk -b omada.cookies \
  -H "Csrf-Token: $TOKEN" \
  -H 'Content-Type: application/json' \
  -X POST \
  "$OMADA_URL/$OMADAC_ID/api/v2/sites/$SITE_ID/setting/wlans/$WLAN_ID/ssids" \
  --data-binary @guest-ssid.json

Use a unique SSID name, a long random passphrase, and WPA2/WPA3-capable settings supported by the access-point firmware. If older clients are important, test them before guests arrive.

4. Verify before handing out the password

curl -sk -b omada.cookies \
  -H "Csrf-Token: $TOKEN" \
  "$OMADA_URL/$OMADAC_ID/api/v2/sites/$SITE_ID/setting/wlans/$WLAN_ID/ssids?currentPage=1&currentPageSize=100" \
  | jq '.result.data[] | select(.name == "ExampleGuest") |
    {name, guestNetEnable, broadcast, vlanEnable, security}'

curl -sk -b omada.cookies \
  -H "Csrf-Token: $TOKEN" \
  "$OMADA_URL/$OMADAC_ID/api/v2/sites/$SITE_ID/devices?currentPage=1&currentPageSize=100" \
  | jq '.result[] | select(.type == "ap") | {name, ip, status, configSyncStatus}'

• Confirm the SSID is present and broadcasting.
• Confirm every access point is online and synchronised.
• Connect a test device and confirm it receives an address and reaches the internet.
• Confirm it cannot reach another guest client or private network service.
• Confirm the existing trusted SSID still works before inviting guests.

When to use a real guest VLAN

Omada guest isolation is a practical answer for a quick, low-risk guest network. Use a dedicated VLAN and router firewall when you need enforceable separation from wired devices, explicit allow rules, IPv6 policy, logging, or multiple network zones.

The VLAN design needs a managed switch or a verified tagged path from the access point to the router. Never turn a live uplink into a trunk as the first step: prepare the router, switching, and rollback path, then test on a spare link if one is available.

A safer automation pattern

1. Back up the controller configuration.
2. Read the current site, WLAN group, and access-point state.
3. Write only the fields required for the change.
4. Verify the controller response and device synchronisation.
5. Test from a client device.
6. Keep a rollback command or saved configuration.

API automation is valuable because it makes the change repeatable. It is safe only when the script also checks its assumptions and proves the result.

For current product behaviour, also consult TP-Link’s Omada guest-network guide and the documentation for your controller and access-point firmware.