Technical Tip: API requests by using the API token authentication method with Postman

[heng]

Description

This article describes how to send an API request by using API token over the request URL as authentication method with Postman.

There are three type of requests for authentication which are Request URL, Request Body and Request Headers.  

If the username/password as the authentication method are used without a proper logout from each of the logins, it will fill up the login session for each API login request until the limit is reached, whereupon the device will deny the next login request. To avoid this issue, it is recommended to use an API token instead. The API token is also referred to as the API key in this context.  

REST API administration using the token authentication method is introduced in FortiManager/FortiAnalyzer version 7.2.2 and above. 

Scope

FortiManager/FortiAnalyzer.

Solution

In FortiManager: 

GUI Method:

1. Create the REST API admin under System Settings -> Administrators -> Create New -> REST API Admin.
2. Generate the API key, edit the REST API admin that has just been created (for example, restapi_admin), and re-generate the API key. The key will be used in the Terraform provider login script.

When using an API key as the authentication method, the trusted host must be provided to allow the source IP address access.

CLI Method:

1. To create the REST API admin using SSH or the console CLI, run the following configuration:

config system admin user
    edit <username>
        set trusthost1 <source subnet> <mask>
        set profileid "Super_User"
        set user_type api
        set rpc-permit read-write
    next
end

2. Use the same CLI command to re-generate the API key:

execute api-user generate-key <API username>  

For example:

execute api-user generate-key restapi_admin
New API key: m4hcu1ud98bymok54ahiuf646gepnekm

In Postman:

In Postman, the sending URL can configured as follows. The variable {{host}} will be the FortiManager/FortiAnalzyer IP address, while {{api-key}} will be the API key obtained from the steps above in the FortiManager/FortiAnalyzer. 

POST method: https://{{host}}/jsonrpc?access_token={{api-key}} 

JSON request body:

{

"id": 1,

"method": "...",

"params": [ ... ]

}

JSON response:

{

"id": 1,

"result": [

"data": [ ... ],

"status": {

"code": 0,

"message": "OK"

},

"url": "..."

],

"session": "..."

}

Example of sending a JSON request to obtain system status /sys/status:

For a complete guide and reference on the JSON-RPC request, refer to and subscribe to the Fortinet Developer Network.

Related articles:

• Technical Tip: Using FortiManager API.
• Fortinet Development Network (FNDN) - FortiManager.
• Fortinet Development Network (FNDN) - FortiGate.
• Technical Tip: Managing the JSON API call with Postman and how to delete, create and update an ADOM ....
• API admin setup.
• Technical Tip: Using Firmware Manager CLI and API.
• Technical Tip: Managing the JSON API call with cURL under Linux/Gnu and how to get, delete and creat....
• Technical Tip: How to run a proxy API call from FortiManager to a managed FortiGate.
• Technical Tip: API requests by using the API token authentication method with Postman.
• Technical Tip: Invalid protocol number when retrieving Service Object from FortiGate registered with....
• Technical Tip: Application of Terraform on FortiManager.