[New Release] Accessing Device Data with SecuReporter OpenAPI Service

Zyxel_JudyH

SecuReporter supports an interface for software to directly interact with the SecuReporter cloud platform. These APIs empower SecuReporter users to retrieve device logs from the past 31 days using an API token.

With the SecuReporter OpenAPI, you can easily access your device data through HTTP requests using any programming language or cURL commands. To utilize this service, ensure your device has a valid SecuReporter license and an OpenAPI Token. These credentials are necessary to authenticate and authorize your requests to the API.

1️⃣Requirement

SecuReporter License

Your device requires a valid SecuReporter license. If your license has expired, please contact the device's owner. Purchase the license from Zyxel marketplace to access Open API Service.

Open API Token

The Open API Service is authorized using OpenAPI Token generated by the agent role on the SecurReporter portal. Your Open API Token is a secret! Users access the device data with Open API Token and do not require my Zyxel account. Never share it with unrelated parties.

Ensure that production requests are routed exclusively through your backend server where your Open API Token can be securely loaded from an environment variable or key management service. You can get the 🔗 Quick Start section (below) if you haven't generated OpenAPI Token yet.

2️⃣Authentication

Request Header

Every request must have an OpenAPI Token in the X-Authorization header and specify the Content-Type in the header as follows:

X-Authorization: Bearer $OPEN_API_TOKEN

Content-Type: application/json

3️⃣Open API Service

The current available OpenAPI Service is as follows, and each service has corresponding quote usage limits. For details, please refer to each service.

🔗 Archive Logs Service

✔️Quick Start

● Confirm the Device's Valid License

1. Click the More button and select "Organization & Device"

2. Select the organization to which the device belongs

3. Confirm the device License Status and check the remaining validity duration

● Generate Open API Token on SecuReporter

The OpenAPI Token operation is restricted to the device’s agent role. Alternatively, contact the device's owner to request authorization and acquire the device’s OpenAPI Token for access privileges.

1. Select the device with a valid SecuRepoter license, click the "API Access" button

2. Click "Create New API Token"

3. Copy the OpenAPI Token

● Add OpenAPI Token to environment variable (Recommended)

[macOS]

1. Open Terminal
   Launch the Terminal application from your Applications folder.
2. Edit Bash Profile
   In the Terminal window, type and execute the following command to open your Bash profile in a text editor: vi ~/.bash_profile
3. Add Environment Variable
   Press i to switch the text editor to insert mode. Then add the following line to set your environment variable, replacing your-open-api-token with your actual token exportOPEN_API_TOKEN='your-open-api-token'.
4. Save and Exit Press esc to switch the text editor to command mode. Type :wqand press enter to save changes and exit the text editor.
5. Load Your Profile To apply the changes, execute the following command in the Terminal: source ~/.bash_profile
6. Verify Environment Variable To verify the correct setting of the environment variable, open your terminal and execute the following command below. If set correctly, it should display your Open APT Token. echo$OPEN_API_TOKEN

[Windows]

1. Access System Properties Right-click on "This PC" and click on "Properties".
2. Open Advanced System Settings In the System Properties window, click on "Advanced System Settings".
3. Navigate to Environment Variables Click the "Environment Variables" button.
4. Add Environment Variables Under the "System variables" section, click "New...". Then, add the following information to set your environment variable, replacing your-open-api-token with your actual token. variable: OPEN_API_TOKEN Variable value: 'your-open-api-token'
5. Verify Environment Variable
   Open a new command prompt. Then, type the following command and press Enter. If set correctly, it should reveal your 'OpenAPI Token'. echo %OPEN_API_TOKEN%

● Language Selection to Make Your First Open API Call

[cURL]

➡️Setup cURL

To check if you have cURL installed, open your Terminal or Command line. Enter the word curl and then press return/enter. If you receive an error stating that cURL is not found, you can install it by following the instructions available on the cURL GitHub repository.

➡️Make Your First Open API Request

Let's try to make your first OpenAPI Request: Download the device's archive logs.

1. Open Terminal
2. Replace the information below and enter the command into the command line/Terminal: ⮕yyyy-MM-dd with a single day within past 31 days (excluding the current day) ⮕mydir with your actual download folder path

⮕ macOS:

curl -X POST \

https://secureporter.cloudcnm.zyxel.com/open-api/v1/archive-logs/download \

-H "Content-Type: application/json" \

-H "X-Authorization: Bearer $OPEN_API_TOKEN" \

-d "{\"device_date\":\"yyyy-MM-dd\"}" \

-o mydir/archive.tar

⮕ Windows:

curl -X POST ^

https://secureporter.cloudcnm.zyxel.com/open-api/v1/archive-logs/download ^

-H "Content-Type: application/json" ^

-H "X-Authorization: Bearer %OPEN_API_TOKEN%" ^

-d "{\"device_date\":\"yyyy-MM-dd\"}" ^

-o mydir\archive.tar

3. Reveal the download progress bar, and download the file to your folder.

✨ Congratulations, you completed your first Open API request! Let's explore more information about Open API.

[Python]

➡️ Setup Python

You can make an OpenAPI request via Python language. To check if you have Python installed, open your Terminal or Command line. Enter the word python and then press return/enter. If you receive an error stating that Python is not found, you can install it by following the instructions available on the official Python website. To use the Requests library, you need at least Python 3.8 or newer.

➡️ Create and Activate a Virtual Environment (Optional)

Navigate to your project directory and create a virtual environment. you can follow the official Python Venv document to create your virtual environment.

Activate the Virtual Environment after creating the virtual environment:

⮕ macOS: source your-virtual-environment-path/bin/activate

⮕ Windows: your-virtual-environment-path\Scripts\activate

➡️ Confirm the Requests Library Installed

If you install requests library success, it displays the requested library version

⮕macOS: source your-virtual-environment-path/bin/activate

⮕Windows: your-virtual-environment-path\Scripts\activate

➡️Make Your First Open API Request

Let's try to request the OpenAPI via the Python request library. Then, create a file named test.py using the terminal or an IDE.

1. Replace the information below and enter the command into the command line/Terminal: ⮕yyyy-MM-dd with a single day within past 31 days (excluding the current day) ⮕mydir with your actual download folder path
2. You can copy and paste one of the examples below:

import os

import requests

# Open API endpoint

open_api_url ="https://secureporter.cloudcnm.zyxel.com/open-api/v1/archive-logs/download"

open_api_token = os.getenv('OPEN_API_TOKEN')

# Save tar file path

# Replace "mydir" with your actual download folder path

tar_file_path ='mydir/archive.tar'

# Define the headers and payload

headers ={

    "X-Authorization":f"Bearer {open_api_token}",

    "Content-Type":"application/json"

}

# Replace "yyyy-MM-dd" with a single day within the past 31 days (excluding the current day)

payload ={

    "device_date":"yyyy-MM-dd"

}

# Make the POST request

response = requests.post(open_api_url, headers=headers, json=payload)

content = response.content

# Check the response

if response.status_code ==200:

    content_type = response.headers['Content-Type']

    if content_type =='application/x-tar':

        withopen(tar_file_path,'wb')as tar_file:

            tar_file.write(content)

        print("Request successed!")

        print("Download Tar File Path:", tar_file_path)

    else:

        print("Request failed!")

        print("Response:", content)

else:

    print("Request failed!")

    print("Status code:", response.status_code)

    print("Response:", content)

After conducting the sample code, download the device's archive log to your folder. ✨ Congratulations, you completed your first OpenAPI request! Let's explore more information about OpenAPI.

For more detailed information about SecuReporter Open API integration and more, please visit our GitHub.