Technical Tip: Using FortiManager API

[oholecek_FTNT]

Description

This article describes about FortiManager API. FortiManager HTTPs API is JSON-RPC.

Unlike the more famous REST API, JSON-RPC does not pass any information in URL or HTTP Method. Additionally, the Status code in HTTP response does not generally relate to result of the API call.

Solution

Usage

Every request is POST request to /jsonrpc URL. There are no authorization headers. Full request is sent inside the HTTP Body, which is JSON formatted. JSON request usually has following five fields:

• method Action that is to be taken by FortiManager. This is commonly get, set, put, delete, etc. depending on what is being configured.
• params Usually further structured, specifying all details of what configuration is to be read, created or updated and how exactly.
• session Authorization token returned by login function (see below). All requests must have it except of login request.
• verbose When used (and enabled), values normally refering by numbers to internal constants are returned as human readable names instead of those numbers.
• id Only used to pair requests and response. It can be anything in the request and FortiManager will use the same ID in its response. This is useful when more requests are sent over the same HTTP(s) connection without waiting for previous response, because in such case responses may come in different order.

More examples & testing

Following sections contain few very basic examples. Much more complex examples grouped by areas with direct test options can be found in our public Postman collection.

The best way is to fork the FortiManager collection and also the default environment into the private workspace where users can edit it. The environment parameters must be updated to match the network and FortiManager user's credentials (+ allowing API access for that user).

Requests can then be called directly from web browser with help of Postman Agent or from Postman application running locally on the computer. If users are missing some example, feel free to send message to @oholecek_FTNT. 

Login and logout

To obtain session key for futher requests, login function must be called first. Session key is valid for configured API idle timeout [System Settings → Admin → Admin Settings → Idle Timeout (API)] or until explicit logout.

By default no user is allowed to use this API. To allow it, either Read or Read-Write must be selected in user's JSON API Access setting [System Settings → Admin → Administrators → ... → Edit].

It is important to log out when all work is done, especially when long idle timeout is set. Otherwise it can happen that all 32 slots (per user) are used and FortiManager reject this user from logins until users timeout or are manually deleted by administrator [System Settings → Dashboard → Current Administrators → ... → Delete].

Example of login request

Details of expected parameters for login request are described on FNDN. Function name in this case is /sys/login/user and method exec. The most important keys in params object are data with user and passwd.

{
    "id": 1,
    "method": "exec",
    "params": [{
        "data": {
            "user": "apiuser",
            "passwd": "apipassword"
        },
        "url": "/sys/login/user"
    }]
}

with response:

{
    "id": 1,
    "result": [{
        "status": {
            "code": 0,
            "message": "OK"
        },
        "url": "/sys/login/user"
    }],
    "session": "TxMw/zbjw+tVZ/JL3bhmYg0vTUpVguYHIQesJXpye4j2vvsqtZaSgKWa+0iLqug+3/074jq8QqmI/KOx4GHkwQ=="
}

Test call can be done with cURL tool:

curl --location --request POST 'https://10.0.0.100/jsonrpc' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "id": 1,
        "method": "exec",
        "params": [{
            "data": {
                "user": "apiuser",
                "passwd": "apipassword"
            },
            "url": "/sys/login/user"
        }]
    }'

Example of logout request

Details of expected parameters for login request are described on FNDN. Function name in this case is /sys/logout and method exec. The only key in params object is url. The request must contain the right session key which is being terminated.

{
    "id": 1,
    "method": "exec",
    "params": [{
        "url": "/sys/logout"
    }],
    "session": "TxMw/zbjw+tVZ/JL3bhmYg0vTUpVguYHIQesJXpye4j2vvsqtZaSgKWa+0iLqug+3/074jq8QqmI/KOx4GHkwQ=="
}

with response:

{
    "id": 1,
    "result": [{
        "status": {
            "code": 0,
            "message": "OK"
        },
        "url": "/sys/logout"
    }]
}

Retrieve FortiManager status

Status request doesn't expect any parameters (except url) as can be seen on FNDN. In response it returns FortiManager's basic operation parameters. Description of each field from the response can be found on the same FNDN page.

{
    "method": "get",
    "params": [
        {
            "url": "/sys/status"
        }
    ],
    "session": "TxMw/zbjw+tVZ/JL3bhmYg0vTUpVguYHIQesJXpye4j2vvsqtZaSgKWa+0iLqug+3/074jq8QqmI/KOx4GHkwQ==",
    "verbose": 1,
    "id": 1
}

with response:

{
    "id": 1,
    "result": [
        {
            "data": {
                "Admin Domain Configuration": "Enabled",
                "BIOS version": "04000002",
                "Branch Point": "0254",
                "Build": "0254",
                "Current Time": "Tue Sep 13 17:15:22 CEST 2022",
                "Daylight Time Saving": "Yes",
                "FIPS Mode": "Disabled",
                "HA Mode": "Stand Alone",
                "Hostname": "vm30",
                "License Status": "Valid",
                "Major": 7,
                "Max Number of Admin Domains": 105,
                "Max Number of Device Groups": 10000,
                "Minor": 0,
                "Offline Mode": "Disabled",
                "Patch": 3,
                "Platform Full Name": "FortiManager-VM64",
                "Platform Type": "FMG-VM64",
                "Release Version Information": " (GA)",
                "Serial Number": "FMGVMSTM11111111",
                "TZ": "Europe/Brussels",
                "Time Zone": "(GMT+1:00) Brussels, Copenhagen, Madrid, Paris.",
                "Version": "v7.0.3-build0254 220202 (GA)",
                "x86-64 Applications": "Yes"
            },
            "status": {
                "code": 0,
                "message": "OK"
            },
            "url": "/sys/status"
        }
    ]
}

Handling errors

As mentioned at the beginning, with FortiManager API the HTTP response status code doesn't say anything about the status of the request. Error status must be checked by looking into status field of the response JSON body. If the code is 0 (as in the response example above) it was executed successfully and returned data is valid. Otherwise the error reason can be found in message field as in following example when attempted to get information about non-existing ADOM:

{
    "method": "get",
    "params": [
        {
            "url": "/pm/pkg/adom/not-existing"
        }
    ],
    "session": "TxMw/zbjw+tVZ/JL3bhmYg0vTUpVguYHIQesJXpye4j2vvsqtZaSgKWa+0iLqug+3/074jq8QqmI/KOx4GHkwQ==",
    "verbose": 1,
    "id": 1
}

with response:

{
    "id": 1,
    "result": [
        {
            "status": {
                "code": -6,
                "message": "Invalid url"
            },
            "url": "/pm/pkg/adom/not-existing"
        }
    ],
    "session": 1793
}