Zyxel Nebula OpenAPI

Zyxel_Carter · January 2022

In September 2021, alongside the release of P12, Nebula introduced the initial version of Nebula OpenAPI, which serves as an interface for software to directly interact with the Nebula cloud platform and Nebula-managed devices. These APIs empower Nebula users to programmatically manage Nebula networks at scale through custom-developed applications. This article serves as an overview and FAQ document for Zyxel Nebula OpenAPI.

Nebula OpenAPI Overview

Zyxel Nebula API is RESTful and HTTPS protected.
Zyxel Nebula API uses API Key instead of OAUTH2 to authenticate.
API key scope is per-Admin, and it shares the same permissions.
For more basic introduction of Zyxel Nebula OpenAPI, please read this.

Support API list

You can find the latest version here. The information in below might not up to date.

For your convenience and better understanding, the table below provides a high-level summary of Nebula OpenAPI categorized by version 0.1.19, excluding non-device related APIs. Always remember to check for the latest version at provided link.

NCC	API path	Note
Listing of Organizations, Sites and Devices	/organizations /organizations/{orgId} /organizations/{orgId}/sites /organizations/{orgId}/sites/devices
License	/license/{orgId}/complement /license/{orgId}/claim /license/{orgId}/claim-result
Firmware status on all devices	/{siteId}/firmware-status
Device online status on all devices	/{siteId}/online-status

Firewall (Only for USG Flex series, ATP series)	API path	Note.
Port status (WAN/LAN)	/{siteId}/gw/{devId}/ports-status
Interface status (Physical / VLAN / IP information)	/{siteId}/gw/{devId}/ports-status
Session limits	/{siteId}/gw/{devId}/traffic-usage	Not session limits, it is the current sessions
Memory status	/{siteId}/gw/{devId}/system-status
CPU status	/{siteId}/gw/{devId}/system-status
Bandwidth usage	/{siteId}/gw/{devId}/traffic-usage	Available values : 2h, 1d, 7d
Device Name, incl. MAC address and serial number (online/offline)	/organizations/{orgId} /organizations/{orgId}/sites/devices
NCC connectivity on/off	/{siteId}/online-status	Device online status on all devices, not for setting

Switch	API path	Note.
Interface status (Physical / VLAN / IP information)	/{siteId}/sw/{devId}/ip-status /{siteId}/sw/{devId}/ports-status
MAC Table per port	/{siteId}/sw/{devId}/l2-mac-table	L2 MAC Table
Full- / Half Duplex	/{siteId}/sw/{devId}/ports-status
Port speed	/{siteId}/sw/{devId}/ports-status
Neighbor info	/{siteId}/sw/{devId}/lldp-neighbor	LLDP
PoE on/off on interface	/{siteId}/sw/{devId}/poe-status
PoE consumption on interface	/{siteId}/sw/{devId}/poe-status
Bandwidth usage	/{siteId}/sw/{devId}/traffic-usage	Available values : 2h, 1d, 7d
Device Name, incl. MAC address and serial number (online/offline)	/organizations/{orgId} /organizations/{orgId}/sites/devices
NCC connectivity on/off	/{siteId}/online-status

WiFi	API path	Note.
Interface status (Physical / VLAN / IP information)	/{siteId}/ap/{devId}/ip-status /{siteId}/ap/{devId}/ports-status	No VLAN
Authentication status (WPA2-PSK, WPA2-Enterprise, etc …) per AP/per SSID	/{siteId}/ap/wlan-settings
SSID (enabled/disabled)	/{siteId}/ap/wlan-settings
VLAN setting on interface and SSID	/{siteId}/ap/wlan-settings
Device Name, incl. MAC address and serial number (online/offline)	/organizations/{orgId} /organizations/{orgId}/sites/devices
NCC connectivity on/off	/{siteId}/online-status	Device online status on all devices, not for setting

How to get started using ZYXEL Nebula OpenAPI?

Prerequisite:
Ensure that your Nebula devices are registered under a Nebula Professional Pack licensed organization. It's important to note that Nebula OpenAPI integration is a feature exclusively available in the Pro Pack

Generate the API key via Nebula Control Center:

To generate a new API key using the Nebula Control Center, follow these simple steps:

Log into the Nebula Control Center: Access your account through the Nebula platform and navigate to the "API Key Management" section under "User's Device and Service."
Generate a New API Key: Click on the "Open API Key" option to start generating a key.
Acknowledge Security Measures: Acknowledge the importance of API key security by checking the prompt that appears. This step helps remind users of the security implications involved in API access.
Copy and Save the Key: Once generated, simply click the copy icon next to the API key. Paste it into your software or system for immediate integration.

How to make API feature request if what I need not available in the latest version of OpenAPI list?

Please forward the ticket/case email to your local Zyxel sales or sales engineer to validate your feature request in terms of its impact on the business. This will assist the Nebula product management team in determining the priority of the request.

Examples to use and test Nebula OpenAPI

Before you begin, ensure that you have the following requirements in place:

APP tool, such as Postman.
API key.

Procedure:

Go to the Postman website and sign up to create an account.
After successfully signing in, go to the "My workspace" section. If you don't have a workspace, you can create a new one.
Within the workspace, locate the "+" button, typically found at the top left of the interface, and click on it to proceed.
Find the "Headers" section. Inside this section, you will see two columns labeled "Key" and "Value". In the "Key" field, enter "X-ZyxelNebula-API-Key". Then, in the corresponding "Value" field, paste the API key that you received from Zyxel support.
Reminder: The API key is tied to your account, so it’s essential to keep it secure and confidential, as it provides access to your organization. If you have any security concerns regarding your API key, don’t hesitate to contact Zyxel support to request a new API key and deactivate the old one.
Insert the API endpoint URL: https://api.nebula.zyxel.com/v1/nebula.
After adding the endpoint URL, include the specific information you wish to retrieve.
For instance, if you want to obtain the organization’s details such as:
a. Name: Organization's name
b. OrgId: Organization's unique ID
c. Mode: Organization's license mode

The modified URL should appear as follows: https://api.nebula.zyxel.com/v1/nebula/organizations

Finally, click on the "Send" button to execute the request.

The response will present the results in the following format:

What is the API token used for in the Site-wide Site settings?

API token which located at Site-wide > Configure > Site settings is specifically used to generate an API token for DPPSK third-party integration.

To learn more about Nebula’s DPPSK solution and how to integrate it with a third-party WiFi onboarding management system, please visit our website.

There is currently a separate API document for DPPSK integration. Please create a support ticket or case and include the necessary information for DPPSK integration.