REST API

Prev Next

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:

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.