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 > 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 > Profile Settings > ACCOUNT SETTINGS screen and in the CLOUD 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 CLOUD API TOKENS section.
5. Go back to the Help > 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 > 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.

Click on the Device Operations heading to expand this section and then click on the /api/device/list tile to expand this operation.
Optional: You can click on section headings above the Parameters section to see code samples in different languages.
In the Parameters section, click on the Try It Out button.
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.
Analyze the Responses section.

Test using Postman

In this section, you will do the same test as above, but using the Postman application.

Postman is a free, GUI-based Windows application for testing APIs. Before you begin, download Postman from the official site and install it. You can register for a Postman account or run the application without an account.

Enter the URL of the API method in the Enter URL or paste text field and set the HTTP method.

To create the URL of the API method, concatenate the URL of the Portnox Cloud API: https://clear.portnox.com:8081/CloudPortalBackEnd with the API method.
For example, for the /api/device/list, use the following URL:
```
https://clear.portnox.com:8081/CloudPortalBackEnd/api/device/list
```
and select the POST method.
Enter your authorization data in the Authorization tab.
1. In the Type field, select the Bearer option.
2. In the Token field, paste your Portnox Cloud API key.
Note:
In this example, we are using the API key to authorize. To use your Portnox Cloud administrator user name and password, select Basic Auth as the Type.
Enter your request JSON code in the Body tab. Then, click on the Send button.
In this example, we are using the same JSON code as in the section above:
```
{
  "Query": {
    "PageNumber": 0,
    "PageSize": 10
  }
}
```

Result: You receive a response from the Portnox Cloud API. You can view the response code in the Pretty tab.

Test using curl

In this section, you will do the same test as above, but using the curl application.

curl is a free application, available for many operating systems, and used to send HTTP requests and get HTTP responses from the command line. Before you begin, download curl from the official site (choose the right package for your operating system) and install it.

Get the curl request from Portnox Cloud or from Postman.

You can write your curl request on your own, or you can get it directly from the Portnox Cloud API testing interface or from Postman.
- If you want to get your curl request from Portnox Cloud, after you execute your request in the Portnox Cloud API testing interface, copy the content of the Curl field.
  
  For example:
```
curl -X POST "https://clear.portnox.com:8081/CloudPortalBackEnd/api/device/list" -H "accept: application/json" -H "Authorization: Bearer AITmunk3KfUCSpcKE9CHqhulhlk" -H "Content-Type: application/json" -d "{ \"Query\": { \"PageNumber\": 0, \"PageSize\": 10 }}"
```
- If you want to get your curl request from Postman, after you prepare your request in Postman, click on the </> icon, select cURL in the field below, and click on the ⧉ icon to copy the curl code.
  
  For example:
```
curl --location 'https://clear.portnox.com:8081/CloudPortalBackEnd/api/device/list' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer AITmunk3KfUCSpcKE9CHqhulhlk' \
--data '{
"Query": {
"PageNumber": 0,
"PageSize": 10
}
}'
```
  Note:
  The curl code from Postman is optimized for the UN*X/Linux shell and may require changes on Windows.
Execute the curl command in your command line window on your operating system.

Result: You receive a response from the Portnox Cloud API.