ZPE Cloud API Resources

ZPE Cloud provides an embedded Representational State Transfer (RESTful) API. This includes API calls to access and modify the ZPE Cloud configuration. Once configured, the REST-based interface is enabled for the users to:

• Submit the requests supporting GET, POST, UPDATE/PUT, and DELETE operations. Use POST requests to submit the commands to the server. Use GET to retrieve information from the server. Use UPDATE/PUT to modify the parameter values. Use DELETE to delete a user or device from the site, group, profile, backup, or organization.

• Retrieve configured data in JSON format.

• Use endpoints, which interact with the API to perform various operations. Each endpoint corresponds to a particular function. For example, user_authenticate is the endpoint for a user to log into the application.

Users can execute the API calls using the REST API GUI explorer provided via ZPE Cloud. For API developers, ZPE Cloud API resources are available here:

• Cloud Users API Reference

• Device Manager API Reference

To access the REST API GUI explorer use the following steps:

1. Log in to the ZPE Cloud application.

2. Enter your credentials.

3. Click About.
   

   

4. Select the applicable API. For example, for the user authentication API, select User API. You will be navigated to the page containing the list of APIs for that function.

5. On the left panel, click the right arrow to display API calls for that function. You can also perform a search with the API name.

Base URL

The ZPE Cloud APIs are available via a secure HTTPS connection. The base URL for all the ZPE Cloud functions is:

https://api.zpecloud.com ( For US users)
https://api.zpecloud.eu (For EU Cloud users)

Response Codes

ZPE Cloud APIs use the following response codes:

Authenticate User

This section shows the API to authenticate users to make the API calls to ZPE Cloud.

Endpoint

/user/auth - This is the endpoint for user login into the application.

Request

{
  "email": "user1@example.com",
  "password": "pwd@1234"
}

Response

{
"id": 2,
"username": "user1",
"email": "user1@example.com",
"first_name": "testuserfn",
"last_name": "testuserln",
"type": "CA",
"first_access": true,
"creation_type": "local",
"company": "ABC",
"companies_count": "1",
"setup_pwd": "pwd@1234",
"session_timeout": 10,
"access_level": "3"
}

The following table shows the list of values you may see in the response.

Examples

This section shows the process of interacting with the ZPE Cloud company's API using cURL or Python for basic operations such as:

1. Logging into the Cloud company using company credentials.

2. Performing a series of API requests: a POST request to add a new group to the company, a GET request to verify the successful addition of the group, a PUT request to edit the newly created group, and a DELETE request to remove the group.

3. Logging out from the ZPE Cloud company.

Note

Requests to company related data and devices requires Authentication on ZPE Cloud, this way, the login to API is the first step required to execute the following up requests.

Remember to logout from the API at the end of the steps in order to avoid keeping an unused session opened.

cURL Examples

These step-by-step instructions will ensure you understand how to manage groups within the ZPE Cloud company's environment using API calls through cURL tool.

NOTE:

It is recommended to use Linux command prompts, such as those in Ubuntu, to execute these commands. Using Windows can cause issues with extra characters, such as backslashes \ and line breaks, which you will need to remove for the commands to work correctly.

Make sure to have cURL installed on your system to accomplish the commands.

About Cookies

The Cookie for ZPE Cloud can be retrieved at the login request. The --cookie-jar and --cookie options can be replaced by the ‘Cookie’ on header of the request, such as:

--header "Cookie: session=uwfmzdngvgw2n5whta73japizga7u53w;"

Logging to ZPE Cloud

1. Open the command prompt from your Operational System.

2. Execute the following command to log into the ZPE Cloud:

   curl -i -X POST 'https://api.zpecloud.com/user/auth' \
   --header 'Content-Type: application/json' \
   --data '{"email": "doc-user.01@zpesystems.com", "password": "-2g3#h&Y}v=4[h|G}lkjhBkk}k[t8<PP&bgDxFVUj$)T*bG^.Qu"}' \
   --cookie-jar cookiefile

   

3. Copy the set-cookie parameter value. See the above screenshot. The cookie is used in the header in the following operations.

Adding Group

Execute the following command to add a group:

curl -i -X POST 'https://api.zpecloud.com/group' \
--header 'Content-Type: application/json' \
--data '{"name": "group_test", "access_level": "1"}' \
--cookie cookiefile

Getting List of Groups

Execute the following command to get the list of groups:

curl -i -X GET 'https://api.staging-zpecloud.com/group' \
--header 'Content-Type: application/json' \
--cookie cookiefile

Editing Group

Execute the following command to edit group using the group ID:

curl -i -X PUT 'https://api.staging-zpecloud.com/group/64598' \
--header 'Content-Type: application/json' \
--data '{"name": "group_test_edited", "access_level": "3"}' \
--cookie cookiefile

Getting Current Group

Execute the following command to get current group using the group ID:

curl -i -X GET 'https://api.staging-zpecloud.com/group/64598' \
--header 'Content-Type: application/json' \
--cookie cookiefile

Deleting Group

Execute the following command to delete a group:

curl -i -X DELETE 'https://api.staging-zpecloud.com/group/64598' \
--header 'Content-Type: application/json' \
--cookie cookiefile

Getting List of Groups

Execute the following command to get the list of groups (after the deletion):

curl -i -X DELETE 'https://api.staging-zpecloud.com/group' \
--header 'Content-Type: application/json' \
--cookie cookiefile

Logging out from ZPE Cloud

Execute the following command to log out from ZPE Cloud:

curl -i -X POST 'https://api.staging-zpecloud.com/user/logout' \
--header 'Content-Type: application/json' \
--cookie cookiefile

Python Examples

These step-by-step instructions will ensure you understand how to manage groups within the ZPE Cloud company's environment using API calls through Python.

Note

It is recommended to use Python3 for the requests. Make sure Session library is installed on your system.

Logging in ZPE Cloud

Create a session to re-use the cookie parameter:

#!/bin/env python3
 
import requests

session = requests.Session()

headers = {'Accept': 'application/json, text/xml'}
payload = {"email": "doc-user.01@zpesystems.com", "password": "-2g3#h&Y}v=4[h|G}lkjhBkk}k[t8<PP&bgDxFVUj$)T*bG^.Qu"}
r = session.post("https://api.zpecloud.com/user/auth", headers=headers, data=payload)
print(f"Auth: {r.status_code}")
print(f"Auth: {r.text}")

#[...continuation]

Getting List of Groups

Execute the following request to get the list of groups:

#[...continuation]

headers = {'Accept': 'application/json, text/xml', 'Content-Type': 'application/json'}
r = session.get("https://api.zpecloud.com/group", headers=headers)
print(f"Auth: {r.status_code}")
print(f"Auth: {r.text}")

#[...continuation]

Logging out from ZPE Cloud

Execute the following request to log out from ZPE Cloud:

#[...continuation]

headers = {'Accept': 'application/json, text/xml', 'Content-Type': 'application/json'}
r = session.post("https://api.zpecloud.com/user/logout", headers=headers)
print(f"Auth: {r.status_code}")
print(f"Auth: {r.text}")

Full script

#!/bin/env python3
 
import requests

session = requests.Session()

headers = {'Accept': 'application/json, text/xml'}
payload = {"email": "doc-user.01@zpesystems.com", "password": "-2g3#h&Y}v=4[h|G}lkjhBkk}k[t8<PP&bgDxFVUj$)T*bG^.Qu"}
r = session.post("https://api.zpecloud.com/user/auth", headers=headers, data=payload)
print(f"Auth: {r.status_code}")
print(f"Auth: {r.text}")

headers = {'Accept': 'application/json, text/xml', 'Content-Type': 'application/json'}
r = session.get("https://api.zpecloud.com/group", headers=headers)
print(f"Auth: {r.status_code}")
print(f"Auth: {r.text}")

headers = {'Accept': 'application/json, text/xml', 'Content-Type': 'application/json'}
r = session.post("https://api.zpecloud.com/user/logout", headers=headers)
print(f"Auth: {r.status_code}")
print(f"Auth: {r.text}")