Using APIs

Administrators can use API calls to a FortiGate to:

• Retrieve, create, update, and delete configuration settings
• Retrieve system logs and statistics
• Perform basic administrative actions, such as a reboot or shut down through programming scripts.

Token-based authentication

There are two types of authentication used to make API calls on the FortiGate: session-based and token-based.

Token-based authentication requires the administrator to generate a token, which is then included in each API request for authentication. A token is automatically generated when a new API administrator is created in FortiOS.

Once the API administrator is created and the token displays, there is no way for the FortiGate to provide this token again. Ensure you record the token, and store it in a safe location; otherwise, you will have to generate a new token.

Creating the API administrator and generating the API token

When creating an API administrator, it is best practice to provide this account (and the associated token) with the minimum permissions required to complete the function. For example, if you only plan to use API calls to retrieve statistics or information from the FortiGate, the account should have read permissions.

The API administrator account used in this topic's examples has full permissions strictly to illustrate various call types and does not adhere to the preceding recommendation.

See REST API administrator for detailed steps to create a REST API administrator.

Making an API call to retrieve information from the FortiGate

The newly created API token is used to query the FortiGate for all firewall addresses. Many applications can be used for this query, and this example uses a web browser to demonstrate the functionality.

General API call

One of the simplest API calls is api/v2/cmdb/firewall/address, which returns all information about all firewall addresses.

To make a general API call:

1. Open the web browser.

2. In the address bar, enter https://<FortiGate_address>/api/v2/cmdb/firewall/address/?access_token=<API_token>.

3. The browser displays the output similar to the following (output shortened for brevity):

   {
     "http_method":"GET",
     "revision":"124.0.206.9538334086041268915.1559577065",
     "results":[
       {
         "q_origin_key":"AD-Server",
         "name":"AD-Server",
         "uuid":"********-****-****-****-************",
         "subnet":"10.100.77.240 255.255.255.255",
         "type":"ipmask",
         "start-mac":"00:00:00:00:00:00",
         "end-mac":"00:00:00:00:00:00",
         "start-ip":"10.100.77.240",
         "end-ip":"255.255.255.255",
         "fqdn":"",
         "country":"",
         "wildcard-fqdn":"",
         "cache-ttl":0,
         "wildcard":"10.100.99.240 255.255.255.255",
         "sdn":"",
         "interface":"",
         "tenant":"",
         "organization":"",
         "epg-name":"",
         "subnet-name":"",
         "sdn-tag":"",
         "policy-group":"",
         "comment":"",
         "visibility":"enable",
         "associated-interface":"",
         "color":0,
         "filter":"",
         "sdn-addr-type":"private",
         "obj-id":"",
         "list":[
         ],
         "tagging":[
         ],
         "allow-routing":"disable"
       },
       {
         "q_origin_key":"AWS-us-east-1a",
         "name":"AWS-us-east-1a",
         "uuid":"********-****-****-****-************",
   			

Formatting an API call

Since a general API call for address objects returns a large amount of information, it may be beneficial to format the API call to display certain information using the format parameter. In this example, the format parameter is used to display the name and comment for each firewall address.

To use the format parameter in an API call:

1. Open the web browser.

2. In the address bar, enter https://<FortiGate_address>/api/v2/cmdb/firewall/address/?access_token=<API_token>&format=name|comment.

3. The browser displays the output similar to the following:

   {
     "http_method":"GET",
     "revision":"160.0.206.9538334086041268915.1559577065",
     "results":[
       {
         "q_origin_key":"AD-Server",
         "name":"AD-Server",
         "comment":""
       },
       {
         "q_origin_key":"AWS-us-east-1a",
         "name":"AWS-us-east-1a",
         "comment":""
       },
       {
         "q_origin_key":"AWS-us-east-1b",
         "name":"AWS-us-east-1b",
         "comment":""
       },
   

Filtering an API call

The filter parameter can be used to specify a field and a keyword to limit what results match and are returned by a call. In this example, the preceding call is used with a filter to return only names and comments for address objects with the word Sales in the name.

To use the filter parameter in an API call:

1. Open the web browser.

2. In the address bar, enter https://<FortiGate_address>/api/v2/cmdb/firewall/address/?access_token=<API_token>&format=name|comment&filter=name=@Sales.

3. The browser displays the output similar to the following:

   {
     "http_method":"GET",
     "revision":"196.0.206.9538334086041268915.1559577065",
     "results":[
       {
         "q_origin_key":"Sales Network",
         "name":"Sales Network",
         "comment":""
       },
       {
         "q_origin_key":"Sales-Portal",
         "name":"Sales-Portal",
         "comment":""
       }
     ],
     "vdom":"root",
     "path":"firewall",
     "name":"address",
     "status":"success",
     "http_status":200,
     "serial":"****************",
     "version":"v6.2.0",
     "build":866
   }
   

For a complete list of API calls, see the Fortinet Development Network (FNDN). A subscription is required to access the FNDN.