API access

The following provides instructions on how to access and call the FortiGate Cloud API. You can find all supported API calls at the FortiGate Cloud REST API documentation.

FortiOS version 7.0 and later versions return Gzipped binary file responses by default. For CURL, you can add the - -compressed tag in your query to get the unzipped plain response.

For FortiGate Cloud API calls, the host address depends on the server environment as follows:

Environment	Host address
Global	api.fortigate.forticloud.com
Europe	euapi.fortigate.forticloud.com
Japan	jpapi.fortigate.forticloud.com

All API calls that this guide includes use the global environment as an example.

To make an API call using a server authentication token:

1. Call the token retrieval API. The following provides an example:

   Request:

   curl -H "Content-Type: application/json" -X POST -d '{"accountId":"xxx","userName":"xxx","password":"xxxxxxxx"}' https://www.forticloud.com/forticloudapi/v1/auth

   Response:

   {"access_token": "EXAMPLETOKEN", "expires_in": 14400, "message": "successfully authenticated", "refresh_token": "syIsrAofcHe67bTFdmhhT5pInnqCXT", "scope": "read write", "status": "success", "token_type": "Bearer"}

   Substitute in your FortiGate Cloud account credentials and host address.

2. You can query all supported FortiGate Cloud APIs using the access token that you retrieved from step 1. The following provides an example:

   Request:

   curl -H "Content-Type: application/json" -H "Authorization: Bearer EXAMPLETOKEN" -X GET https://www.forticloud.com/forticloudapi/v1/devices

   Response:

   [{"sn":"","name":"FortiGate-100D","timeZone":-7.0,"tunnelAlive":true,"contractEndTime":0,"model":"FortiGate 100D","firmwareVersion":"6.2.8","management":false,"initialized":false,"subAccountOid":793,"ip":"172.16.30.193","latitude":null,"longitude":null,"total":8,"trial":false},{"sn":"FG60DP4614004455","name":"FG60DP4614004455-Daniel-FGT","timeZone":-7.0,"tunnelAlive":false,"contractEndTime":0,"model":"FortiGate","firmwareVersion":"6.0.9","management":true,"initialized":false,"subAccountOid":-1,"ip":"172.16.93.119","latitude":null,"longitude":null,"total":8,"trial":true},{"sn":"FGT60ETK1809A1GX","name":"FGT60ETK1809A1GX","timeZone":-8.0,"tunnelAlive":false,"contractEndTime":0,"model":"FortiGate","firmwareVersion ...

To make an API call using an IAM user authentication token:

1. If you do not already have one, create an Identity & Access Management (IAM) API user:
   1. Log in to the IAM portal using your FortiGate Cloud account credentials.
   2. Go to API Users, then click ADD API USER. Click Next.
   3. Under Effective Portal Permissions, select FortiGate, then ADD. Click Next.
   4. Click Edit. Toggle Allow Portal Access to YES. Under Access Type, select Admin. Click CONFIRM.
   5. Click DOWNLOAD CREDENTIALS. Open the downloaded file to view your username and password.
2. Retrieve the access token by calling the FortiAuthenticator token retrieval API: /oauth/token/. The following provides an example where the FortiAuthenticator IP address is customerapiauth.fortinet.com:

   Request:

   curl -H "Content-Type: application/json" -X POST -d https://customerapiauth.fortinet.com/api/v1/oauth/token/ '{"username":"AC0F1454-3CCD-4523-8B3C-4412156CB197","password":"a679bc11d6011e6ea3a7390cef0cd66b!1Aa","client_id":"fortigatecloud","grant_type":"password"}'

   Response:

   {"access_token": "EXAMPLETOKEN", "expires_in": 14400, "message": "successfully authenticated", "refresh_token": "syIsrAofcHe67bTFdmhhT5pInnqCXT", "scope": "read write", "status": "success", "token_type": "Bearer"}

3. You can query all supported FortiGate Cloud APIs using the access token that you retrieved from step 2. The following provides an example:

   Request:

   curl -H "Content-Type: application/json" -H "Authorization: Bearer EXAMPLETOKEN" -X GET https://www.forticloud.com/forticloudapi/v1/devices -k

   Response:

   [{"sn":"FG100D3G15803161","name":"FortiGate-100D","timeZone":-7.0,"tunnelAlive":true,"contractEndTime":0,"model":"FortiGate 100D","firmwareVersion":"6.2.8","management":false,"initialized":false,"subAccountOid":793,"ip":"172.16.30.193","latitude":null,"longitude":null,"total":8,"trial":false},{"sn":"FG60DP4614004455","name":"FG60DP4614004455-Daniel-FGT","timeZone":-7.0,"tunnelAlive":false,"contractEndTime":0,"model":"FortiGate","firmwareVersion":"6.0.9","management":true,"initialized":false,"subAccountOid":-1,"ip":"172.16.93.119","latitude":null,"longitude":null,"total":8,"trial":true},{"sn":"FGT60ETK1809A1GX","name":"FGT60ETK1809A1GX","timeZone":-8.0,"tunnelAlive":false,"contractEndTime":0,"model":"FortiGate","firmwareVersion ...

To call FortiOS APIs via FortiGate Cloud:

1. If the management feature is disabled on the desired FortiGate, enable it by calling devices/{sn}/management. The following provides an example:

   Request:

   curl -H "Content-Type: application/json" -H "Authorization: Bearer EXAMPLETOKEN" -X PUT -d '{"management":true, "username":"xxx", "password":"xxx"}' https://www.forticloud.com/forticloudapi/v1/devices/FGT60D461xxxxxxx/management

2. You can proxy any FortiOS API via FortiGate Cloud. The format for calling FortiOS APIs from FortiGate Cloud is as follows:

   https://www.forticloud.com/forticloudapi/v1/fgt/<SN>/<FortiOS API>

   The following provides an example request where the FortiGate serial number is FGT60D461xxxxxxx and the API being called is /api/v2/monitor/fortiguard/service-communication-stats, which retrieves historical statistics for communication with FortiGuard services.

   Request:

   curl -H "Content-Type: application/json" -H "Authorization: Bearer EXAMPLETOKEN" https://www.forticloud.com/forticloudapi/v1/fgt/FGT60D461xxxxxxx/api/v2/monitor/fortiguard/service-communication-stats

For FortiOS API information, see the FortiOS REST API documentation.