How to use the API

You can use the API to make configuration changes manually to XML strings.

Introduction

To make configuration changes using the API, do as follows:
  • Create an administrator profile with read-write permission for the modules you want to update.
  • Attach the administrator profile to an administrator record.
  • Allow the following activities:
    • API configuration.
    • API access from the IP address of the administrator's endpoint device.
    • Access to the administrative services of XG Firewall from the administrator's zone.
  • Submit the XML string. In this example, we enter the string in the address bar of a browser.

Create an administrator profile for making configuration changes

You create an administrator profile with read-write permission for objects and network.

  1. Go to Profiles > Device access and create an administrator profile with specific rights.
  2. Click Save.

    The following image shows an example of how to configure the settings:


    Administrator profile with read-write permission

Create an administrator

You create a user and add the administrator profile.

When you add a user with the API administrator profile, you can limit the administrator's rights based on the profile. Alternatively, you can use an existing administrator account.
  1. Go to Authentication > Users and click Add.
  2. Set User type to Administrator.
  3. Select the API administrator profile you created.
  4. To allow access for a specific time, select the Access time.
  5. To allow access only from specific IP addresses, select an option for Login restriction for device access.
  6. Click Save.

    The following image shows an example of how to configure the settings:


    APIAdminUser

Allow API access

You allow API access for the administrator you created.

You turn on API configuration and allow API access from the administrator's IP address. You also allow access to the administrative services of XG Firewall.

  1. Specify the API configuration settings:
    1. Go to Backup and firmware > API.
    2. Select API configuration.
    3. For Allowed IP address, select the IP address from which you'll make the API request.
    4. Click Apply.

    The following image shows an example of how to configure the settings:


    Allow API access
  2. To allow access to administrative services from the zone containing the administrator's IP address, do as follows:
    1. Go to Administration > Device access. Under Admin services, select the administrator's zone for HTTPS and SSH.

      If you want to allow access from the WAN zone, we recommend that you create an exception rule limiting the access for specific services.

    2. Scroll down to Local service ACL exception rule. Click Add, and create an exception for the zone.
    3. In this example, we specify the following settings:

      Setting

      Description

      Source zone

      LAN

      Source network/host

      API administrator

      Destination host

      Port2

      Services

      HTTPS

      SSH

      Action

      Accept

    4. Click Save.
      The following image shows an example of how to configure the settings:

      Local service exception rule for WAN access

Get, add, update, or delete an IP host

You get, add, update, or delete an IP host using a browser's address bar.

Paste the following strings in a browser's address bar based on your requirement:

  • Get the IP hosts in the configuration:
    https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>API admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc
    </Password></Login><Get><IPHost><Name></Name><IPFamily></IPFamily><HostType></HostType><IPAddress></IPAddress></IPHost></Get></Request>

    You see the list of configured IP hosts.

  • Add an IP host:
    https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>API admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc
    </Password></Login><Set><IPHost><Name>Test10</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType><IPAddress>198.1.2.1</IPAddress></IPHost></Set></Request>

    Go to Hosts and services > IP host, and see the list for the IP host Test10.

  • Update the IP address of Test10:
    https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>API admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc
    </Password></Login><Set><IPHost><Name>Test10</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType><IPAddress>198.1.3.3</IPAddress></IPHost></Set></Request>
  • Delete the IP host Test10:
    https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>API admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc
    </Password></Login><Remove><IPHost><Name>Test10</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType><IPAddress>198.1.3.3</IPAddress></IPHost></Remove></Request>