Description
This article describes how to use 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 the HTTP response does not generally relate to the result of the API call.
Scope
FortiManager.
Solution
Usage.
Every request is a POST request to /jsonrpc URL. There are no authorization headers. The full request is sent inside the HTTP Body, which is JSON formatted. JSON request usually has the 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 the login function (see below). All requests must have it except for login requests.
- verbose When used (and enabled), values normally referring by numbers to internal constants are returned as human-readable names instead of those numbers.
- id Only used to pair requests and responses. 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 a previous response, because in such cases responses may come in a different order.
More examples & testing.
The following sections contain a few very basic examples. Much more complex examples grouped by areas with direct test options can be found in the 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 a web browser with the help of a Postman Agent or from a Postman application running locally on the computer. If users are missing some examples, feel free to send a message to @oholecek_FTNT.
Login and logout.
To obtain the session key for further requests, the login function must be called first. The 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 the user's JSON API Access setting (System Settings → Admin → Administrators → ... → Edit).
It is important to log out when all work is done, especially when a long idle timeout is set. Otherwise, all 32 slots (per user) can be used and FortiManager rejects this user from logins until the user timeout or is manually deleted by the administrator (System Settings → Dashboard → Current Administrators → ... → Delete).
Example of login request.
Details of expected parameters for login requests are described on FNDN. The function name in this case is /sys/login/user and method exec. The most important keys in the params object are data with user and passwd.
{
"id": 1,
"method": "exec",
"params": [{
"data": {
"user": "apiuser",
"passwd": "apipassword"
},
"url": "/sys/login/user"
}]
}
With the response:
{
"id": 1,
"result": [{
"status": {
"code": 0,
"message": "OK"
},
"url": "/sys/login/user"
}],
"session": "TxMw/zbjw+tVZ/JL3bhmYg0vTUpVguYHIQesJXpye4j2vvsqtZaSgKWa+0iLqug+3/074jq8QqmI/KOx4GHkwQ=="
}
Test calls can be done with the 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 requests are described on
FNDN. The function name in this case is
/sys/logout and method
exec. The only key in the
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 the response:
{
"id": 1,
"result": [{
"status": {
"code": 0,
"message": "OK"
},
"url": "/sys/logout"
}]
}
Retrieve FortiManager status.
Status request does not expect any parameters (except
url) as can be seen on
FNDN. In response, it returns FortiManager's basic operation parameters. A 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 the 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 does not 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 the following example when attempting 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 the response:
{
"id": 1,
"result": [
{
"status":
{
"code": -6,
"message": "Invalid url" },
"url": "/pm/pkg/adom/not-existing"
}
],
"session": 1793
}
Related document:
FMG JSON API Introduction
