Zyxel Nebula OpenAPI

Zyxel_Carter

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, and as of now, the most recent version is 0.1.26

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

Applying API key through support ticket/case:
Since Nebula OpenAPI is still in its early stages and continuously evolving, it is not yet generally available. To provide you with better support during this process, we recommend reaching out to your local/regional Zyxel office or accessing the NCC Help Center directly to create a support ticket/case for applying an API key. Kindly include the necessary information when doing so.

• The main contact window with the registered Zyxel account.
• Which APIs you are going to try, and the information about your developed applications.

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:

1. APP tool, such as Postman.
2. API key.

Procedure:

1. Go to the Postman website and sign up to create an account.
2. After successfully signing in, go to the "My workspace" section. If you don't have a workspace, you can create a new one.
3. Within the workspace, locate the "+" button, typically found at the top left of the interface, and click on it to proceed.
   
   
4. 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.
   
   
5. 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.