Zyxel Nebula OpenAPI

Zyxel_Carter
Zyxel_Carter Posts: 62  Zyxel Employee
First Anniversary Friend Collector First Comment
edited August 2023 in Other Topics

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.25

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.