The AppGate ZTNA admin UI exclusively uses REST API calls to the Controller. AppGate ZTNA provides a subset of these Controller APIs in OpenAPI v3 format for general use. To use an undocumented API call, contact AppGate support.
The Controller APIs support nearly all actions available in the admin UI. For example, you can script entitlement additions from an external provisioning system, so that when the system creates a new server instance, it automatically adds the related entitlement using the appropriate REST API call.
Getting started with the Controller REST API
You will need the following:
Admin access to port 8443 on a Controller appliance.
An API user with relevant permissions, excluded from two-factor authentication (2FA) in Settings > MFA for Admins.
The API Specification.
The admin rights configured for the API user in the admin UI apply to the REST APIs as well. For example, an admin with rights only for entitlements can use only GET /entitlements, GET /entitlements/{id}, PUT /entitlements/{id}, and POST /entitlements.
Code example using Controller APIs
The following example listens to AppGate ZTNA audit logs through rsyslog messages and acts on ALERT messages — for example, removing a user's onboarding cookie or adding the user to the denylist.
import json
import socketserver
import sys
import os
import requests
# edit the values below
CONTROLLER_URL = "https://controller1.company.com:8443"
CA_PATH = os.path.join(os.path.dirname(os.path.realpath(__file__)), "ca.pem")
PROVIDER = "local"
USERNAME = "username"
PASSWORD = "password"
API_VERSION = 22
# do not edit anything below
LISTEN_HOST, LISTEN_PORT = "127.0.0.1", 5140
class SyslogHandler(socketserver.BaseRequestHandler):
def handle(self):
data = bytes.decode(self.request[0].strip())
if len(data) == 0:
print("zero len message received")
return
# parse to JSON
jlog = json.loads(data)
# print(jlog["event_type"] + " received")
if jlog["event_type"] == "ip_access" and jlog["action"] == "alert":
dn = jlog["distinguished_name"]
print(f"ALERT received for {dn}")
blacklist_user(dn)
revoke_tokens(dn)
else:
# print("skipping " + jlog["event_type"])
pass
def login():
headers = {"Accept": f"application/vnd.appgate.peer-v{API_VERSION}+json",
"Content-Type": "application/JSON"}
# authenticate
data = {"machineId": "f0031c00-0522-43b3-a642-ae23cfd1bc22",
"providerName": PROVIDER, "username": USERNAME, "password": PASSWORD}
res = requests.post(f"{CONTROLLER_URL}/admin/login",
verify=CA_PATH, headers=headers, data=json.dumps(data), timeout=5)
if res.status_code != 200:
print(f"CONTROLLER_URL login failed with http {str(res.status_code)}")
sys.exit(-1)
token = json.loads(res.text)["token"]
headers["Authorization"] = f"Bearer {token}"
return headers
def blacklist_user(dn):
auth_headers = login()
# dn without deviceid
user_dn = dn.split(",", 1)[1]
data = {"userDistinguishedName": user_dn, "reason": "suspicious traffic"}
res = requests.post(f"{CONTROLLER_URL}/admin/blacklist",
data=json.dumps(data), verify=CA_PATH, headers=auth_headers)
print(f"{user_dn} blacklisted {str(res.status_code)}")
return res.status_code
def revoke_tokens(dn):
auth_headers = login()
data = {"distinguishedNameFilter": dn, "revocationReason": "api revocation for alert", "delayMinutes": 0}
res = requests.post(f"{CONTROLLER_URL}/admin/on-boarded-devices/revoke-tokens",
data=json.dumps(data), verify=CA_PATH, headers=auth_headers)
print(f"{dn} tokens revoked {str(res.status_code)}")
return res.status_code
if __name__ == "__main__":
print("========================================================")
print(f"Appgate SDP Alert Handler Started on {str(LISTEN_PORT)}")
print("========================================================")
with socketserver.UDPServer((LISTEN_HOST, LISTEN_PORT), SyslogHandler) as server:
server.serve_forever(poll_interval=0.5)Disclaimer
AppGate reserves the right to change REST API calls when a new version is released. Documentation is updated accordingly when changes are made. Any scripts provided by the AppGate ZTNA Professional Services team or included as examples in this manual are delivered as-is, without warranty of any kind. AppGate ZTNA disclaims all implied warranties, including any implied warranties of merchantability or fitness for a particular purpose. The customer is responsible for any maintenance arising from the use or performance of these sample scripts and related documentation.