Testing the Portnox Cloud REST API

In this topic, you will learn how to test the Portnox™ Cloud REST API by using the interface in the Portnox Cloud web portal.

Authorize with the Cloud API

To use the Portnox Cloud API, you must first authorize with the API. Without authorization, all other API operations will fail. In this section, you will learn about two ways to authorize.

  • Option 1: Authorize using your Portnox Cloud administrator account.
    1. Go to the Help > CLEAR API REFERENCE screen.
    2. Click on the Authorize button.

    3. In the AVAILABLE AUTHORIZATIONS window, in the Basic authorization section, enter your Portnox Cloud administrator Username and Password.

      Note: You cannot authorize with the API using external authentication providers such as Microsoft Entra ID or Google Workspace. You must use a locally managed Portnox Cloud administrator account.
      Warning: Portnox Cloud does not check your credentials at this stage. You will only know if you used a correct username and password once you start performing operations with the API.
    4. Click on the Close button.
  • Option 2: Authorize using your API key.
    1. Go to the Settings > ACCOUNT SETTINGS screen and in the CLEAR API TOKENS section, click on the Generate token link to generate a new API token (key).

    2. In the GENERATE A NEW TOKEN window, enter the Name for this token and select whether the token Never expires or expires On date. Then, click on the Generate token button.

    3. Click on the  ⧉  icon to copy the value of the token and paste this value into a temporary text file.
      Note: This is the only time you can copy the token value. If you close this window, you will not be able to copy this value later. If you forget to copy the value, you must delete the current token and create a new one, and then copy the value of the new one.

    4. Click on the Close button. The token will be listed in the CLEAR API TOKENS section.

    5. Go back to the Help > CLEAR API REFERENCE screen and click on the Authorize button.

    6. In the AVAILABLE AUTHORIZATIONS window, paste the value of the token (key) that you copied earlier into the Value field in the apiKey section, and then click on the Authorize button.

Test the Portnox Cloud REST API

In this section, you will perform example operations using the Portnox Cloud REST API to see how it works.

This example shows how to use the /api/device/list operation to fetch a list of accounts and their devices.

Warning: In this example, we selected an operation that does not change the state of the tenant. However, all actions performed in the Portnox Cloud REST API test interface (Help > CLEAR API REFERENCE) are actual API operations. All operations that change states, such as creation or deletion operations, actually change the configuration of your tenant. Be careful when executing these operations to test the API.
  1. Click on the Device Operations heading to expand this section and then click on the /api/device/list tile to expand this operation.

  2. Optional: You can click on section headings above the Parameters section to see code samples in different languages.
  3. In the Parameters section, click on the Try It Out button.

  4. In the request section, click on the Model link to learn how to modify values in the request, then click on the text field and modify values as needed, and finally click on the Execute button.

  5. Analyze the Responses section.