FortiNAC

REST API v2 Configuration

Version: 8.7, 8.8
Date: August 26, 2020
Rev: A

1
FORTINET DOCUMENT LIBRARY
http://docs.fortinet.com

FORTINET VIDEO GUIDE

http://video.fortinet.com

FORTINET KNOWLEDGE BASE

http://kb.fortinet.com

FORTINET BLOG
http://blog.fortinet.com

CUSTOMER SERVICE & SUPPORT

http://support.fortinet.com

FORTINET COOKBOOK
http://cookbook.fortinet.com

NSE INSTITUTE
http://training.fortinet.com

FORTIGUARD CENTER
http://fortiguard.com

FORTICAST
http://forticast.fortinet.com

END USER LICENSE AGREEMENT

http://www.fortinet.com/doc/legal/EULA.pdf

2
Contents
Overview ............................................................................................................................................... 4
What it Does ...................................................................................................................................... 4
How it Works ..................................................................................................................................... 4
Procedure Overview .......................................................................................................................... 4
Requirements .................................................................................................................................... 4
Configuration ........................................................................................................................................ 5
Determine API Request Source Address(es)..................................................................................... 5
Configure Administrator Account ..................................................................................................... 5
Issue API Request ............................................................................................................................. 6
Appendix ............................................................................................................................................... 7
Regenerate API Token ...................................................................................................................... 7
Examples ........................................................................................................................................... 7
Set Authorization in Postman ....................................................................................................... 7
Total Device Count ........................................................................................................................ 7
Full Device List .............................................................................................................................. 8
Group Information ......................................................................................................................... 9
Host Record Information ............................................................................................................. 10
Create Host Group ....................................................................................................................... 11
Add Host to Host Group............................................................................................................... 13
Disable Host ................................................................................................................................. 14
Enable Host.................................................................................................................................. 15

3
Overview
This document provides guidance on how to access the FortiNAC REST API. For documentation
on the full FortiNAC REST API Schema, refer to the to the REST API v2 reference manual in the
Fortinet Document Library.

What it Does
FortiNAC's REST API is a standardized method for other systems to interact with FortiNAC to
perform configuration and monitoring operations.

How it Works
Each resource in the REST API is identified by a named URL, and is accessed using standard HTTP
methods (HEAD, GET, POST, PATCH, DELETE).

Accessing the API is accomplished using curl or another API testing application suite (such as
Postman). Each REST API request requires an API token to be authenticated. An API token is
generated by creating a REST API admin user in FortiNAC.

Distributed Deployments: API requests can be sent to the Control Manager (FNC-M) to retrieve
information for all managed pods.

Procedure Overview
1. Determine source address(es) from which API requests will be issued: This is required in
order to ensure the API token is being used by a trusted source. This can be either
individual addresses or networks.
2. Configure an administrator account in FortiNAC to allow REST API access.
3. Connect to the FortiNAC Server Administrator Interface and issue the desired API request.

Requirements
FortiNAC 8.7 or higher

4
Configuration
Determine API Request Source Address(es)
Identify the individual addresses or networks from which admin users will be sending API
requests. Record this information for use in creating the administrator account.

Configure Administrator Account

Modify or create an administrator account to allow REST API access.

1. In the FortiNAC Administration UI, navigate to Users > Admin Users.

2. Click Add or select an existing user and click Modify.
3. Click Allow REST API Access for this Admin User. The Token value will appear below.

Abc123xxxZYFbbbbbbbcccccccccc

4. Copy the API Token value for use in the API queries. Note: Token value does not display
again after leaving the screen.
5. Specify one or more subnets from which requests to the REST API are allowed. Under
Allowed Subnets, click Add.
6. Enter the subnet and mask of the allowed network. To allow all subnets, enter 0.0.0.0/0.

7. Click OK.
8. Click OK again to save user record.

Note: If the API Token is lost or forgotten, it can be regenerated by modifying the Admin User and
clicking the Regenerate Token button. See Regenerate API Token in the Appendix.

5
Issue API Request
Curl or another API testing application suite (such as Postman) can be used to issue API requests.
All requests require the API token value previously recorded (Authorization: Bearer token) to be
included in the header. Postman examples are listed in the Appendix.

URI:
https://<FortiNAC address>/api/v2/<database resource path>

To view the available API resources that can be accessed (REST API schema), refer to the REST
API v2 reference manual in the Fortinet Document Library.

Example: Retrieve the total number of devices in Topology.

URI: https://<FortiNAC address>/api/v2/device/count/all

Curl command:
curl -k --location --request GET
'https://myserver.company.com:8443/api/v2/device/count/all' --header 'Authorization:
Bearer 3abcfdethgsdybbbbcccccc'

Result:
{"status":"success","errorMessage":null,"results":[],"total":37}

See Appendix for the following examples:

Retrieve the list of devices in Topology
Retrieve information for all groups in the database
Retrieve information for a specific host record via MAC address
Create host group
Add Host to Host Group
Disable Host
Enable Host

6
Appendix
Regenerate API Token
If the API Token is lost or forgotten, it can be regenerated in the Admin User record.
1. Navigate to Users > Admin Users.
2. Double click on the user or right click and select Modify.
3. Click the Regenerate Token button.

4. Copy the API Token value for use in the API queries. The value can be pasted into the
Notes section above, if desired, for easy reference. Note: Token value does not display again
after leaving the screen.

Examples
Set Authorization in Postman
Must be set for each query when using Postman. Enter the API Token Value generated in FNAC.
1. Click Authorization
2. Select type Bearer Token
3. Paste FNAC Token value in the Token field in the right panel

<API Token Value>

4. Click Save

Total Device Count

Retrieve the total number of devices in Topology.

Curl:
Command:
curl -k --location --request GET 'https:// <FortiNAC Server Name>:8443/api/v2/device/count/all' --header
'Authorization: Bearer <API Token value>'

Result:
{"status":"success","errorMessage":null,"results":[],"total":37}

7
Postman
1. Set Authorization
2. Click Headers
3. Under Key enter Content-Type
4. On the same line under Value, enter application/json

5. Set Method and URI in the top fields

Method: GET
URI: https://<FortiNAC Server Name>:8443/api/v2/device/count/all

6. To save request, click Save

7. Click Send

Results display at the bottom.

Full Device List

Retrieve the list of devices in Topology:

Curl
Command:
curl -k --location --request GET 'https:// <FortiNAC Server Name>:8443/api/v2/device' --header
'Authorization: Bearer <API Token value>'

8
Postman
1. Set Authorization
2. Click Headers
3. Under Key enter Content-Type
4. On the same line under Value, enter application/json

5. Set Method and URI in the top fields

Method: GET
URI: https://<FortiNAC Server Name>:8443/api/v2/device/
6. To save request, click Save
7. Click Send

Results display at the bottom. Click on the magnifying glass in the panel containing the results
in order to search content.

Group Information
Retrieve information for all groups in the database. This is helpful when needing to identify a
group database id (required when modifying a group, such as adding or removing a member).

Curl
Command:
curl -k --location --request GET 'https:// <FortiNAC Server Name>:8443/api/v2/system/group' --header
'Authorization: Bearer <API Token value>'

Postman
1. Set Authorization
2. Click Headers
3. Under Key enter Content-Type
4. On the same line under Value, enter application/json

9
 5. Set Method and URI in the top fields
Method: GET
URI: https://<FortiNAC Server Name>:8443/api/v2/system/group
6. To save request, click Save
7. Click Send

Results display at the bottom. To locate information for specific group, click on the magnifying
glass in the panel containing the results and search by name.

Host Record Information

Retrieve information for a specific host record via MAC address. This is helpful when needing to
identify a host database id (required when modifying a host, such as adding or removing from a
group).

Note: MAC address entry must use capital letters and colons (:). Otherwise, an error is generated.

Curl
Command:
curl -k --location --request GET 'https:// <FortiNAC Server Name>:8443/api/v2/host/by-
mac/<xx:xx:xx:xx:xx:xx>' --header 'Authorization: Bearer <API Token value>'

Postman
1. Set Authorization
2. Click Headers
3. Under Key enter Content-Type
4. On the same line under Value, enter application/json

10
 5. Set Method and URI in the top fields
Method: GET
URI: https://<FortiNAC Server Name>:8443/api/v2/host/by-mac/<xx:xx:xx:xx:xx:xx>
6. To save request, click Save
7. Click Send

Results display at the bottom. Click on the magnifying glass in the panel containing the results
in order to search content. If locating the host record’s database id, search for “id”. Record the
first instance found.

Create Host Group

Create host group and set the following:
Group name
elementClass = 8
Days valid = <Number of days the host record will remain in the database after creation.>
Days inactive = <Number of consecutive days the host must be inactive to be aged out of the
database.>

Curl
Command:
curl -k --location --data '{"name": "<Group Name>","elementClass":8, "daysValid":0,"daysInactive":0}' -X
POST 'https:// <FortiNAC Server Name>:8443/api/v2/system/group/host' --header 'Authorization: Bearer <API
Token value>' -H "Content-Type: application/json"

Postman
1. Set Authorization
2. Click Headers
3. Under Key enter Content-Type
4. On the same line under Value, enter application/json

11
 5. Set Method and URI in the top fields
Method: POST
URI: https://<FortiNAC Server Name>:8443/api/v2/system/group/host
6. Click Body then raw
7. Enter the following text in the field below:
{"name": "<Group Name>","elementClass":8, "daysValid":0,"daysInactive":0}

8. To save request, click Save

9. Click Send

Validate in UI: Navigate to System > Groups. The group should now be listed.

12
Add Host to Host Group
Curl
Command:
curl -k --location --data-urlencode 'elemID=<host database ID>' --data-urlencode 'groupID=<group database
ID>' --data-urlencode 'type=8' -X POST 'https://<FortiNAC Server Name>:8443/api/v2/system/group/add-
members' --header 'Authorization: Bearer <API Token Value>' --header 'Content-Type: application/x-www-
form-urlencoded'

Postman
1. Set Authorization
2. Set Method and URI in the top fields
Method: POST
URI: https://<FortiNAC Server Name>:8443/api/v2/system/group/membership
3. Click Body then x-www-form-urlencoded
4. Enter the following text in the field below:

KEY VALUE

MemberID <Host database ID>

Can be obtained by querying host record information in the database
groupID <Group database ID>
Can be obtained by querying group information in the database
type 8 (registered host)

5. To save request, click Save

6. Click Send

Validate in UI: Navigate to System > Groups. Select group and click Group Membership.

13
Disable Host
Curl
Command:
curl -k --location --data-urlencode 'mac=<MAC address using colons and capitals>' -X POST
'https://<FortiNAC Server Name>:8443/api/v2/host/disable-by-mac' --header 'Authorization: Bearer <API
Token value>' --header 'Content-Type: application/x-www-form-urlencoded'

Postman
1. Set Authorization
2. Set Method and URI in the top fields
Method: POST
URI: https://<FortiNAC Server Name>:8443/api/v2/host/disable-by-mac
3. Click Body then x-www-form-urlencoded
4. Enter the following text in the field below:

KEY VALUE

mac <host MAC address>

5. To save request, click Save.

6. Click Send.

Validate in UI: Search for the MAC address under Hosts > Host View. The icon should look
similar to one of the following:

14
Enable Host
Curl
Command:
curl -k --location --data-urlencode 'mac=<MAC address using colons and capitals>' -X POST
'https://<FortiNAC Server Name>:8443/api/v2/host/enable-by-mac' --header 'Authorization: Bearer <API
Token value>' --header 'Content-Type: application/x-www-form-urlencoded'

Postman
1. Set Authorization
2. Set Method and URI in the top fields
Method: POST
URI: https://<FortiNAC Server Name>:8443/api/v2/host/enable-by-mac
3. Click Body then x-www-form-urlencoded
4. Enter the following text in the field below:

KEY VALUE

mac <host MAC address>

5. To save request, click Save

6. Click Send

Validate in UI: Search for the MAC address under Hosts > Host View. The icon should look
like one of the following:

15
Copyright© 2020 Fortinet, Inc. All rights reserved. Fortinet®, FortiGate®, FortiCare® and FortiGuard®, and certain other marks are registered trademarks of Fortinet, Inc., in
the U.S. and other jurisdictions, and other Fortinet names herein may also be registered and/or common law trademarks of Fortinet. All other product or company names
may be trademarks of their respective owners. Performance and other metrics contained herein were attained in internal lab tests under ideal conditions, and actual
performance and other results may vary. Network variables, different network environments and other conditions may affect performance results. Nothing herein represents
any binding commitment by Fortinet, and Fortinet disclaims all warranties, whether express or implied, except to the extent Fortinet enters a binding written contract, signed
by Fortinet’s General Counsel, with a purchaser that expressly warrants that the identified product will perform according to certain expressly-identified performance metrics
and, in such event, only the specific performance metrics expressly identified in such binding written contract shall be binding on Fortinet. For absolute clarity, any such
warranty will be limited to performance in the same ideal conditions as in Fortinet’s internal lab tests. In no event does Fortinet make any commitment related to future
deliverables, features or development, and circumstances may change such that any forward-looking statements herein are not accurate. Fortinet disclaims in full any
covenants, representations, and guarantees pursuant hereto, whether express or implied. Fortinet reserves the right to change, modify, transfer, or otherwise revise this
publication without notice, and the most current version of the publication shall be applicable.

16