Fortinet Document Library

Version:


Table of Contents

21.4.0
Download PDF
Copy Link

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.

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

Environment

Host address

Global

www.forticloud.com

Europe

europe.forticloud.com

Japan

jp.forticloud.com

All API calls that this guide includes uses 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 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

    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 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://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 not already enabled 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://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://forticloud.com/forticloudapi/v1/fgt/FGT60D461xxxxxxx/api/v2/monitor/fortiguard/service-communication-stats

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

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.

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

Environment

Host address

Global

www.forticloud.com

Europe

europe.forticloud.com

Japan

jp.forticloud.com

All API calls that this guide includes uses 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 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

    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 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://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 not already enabled 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://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://forticloud.com/forticloudapi/v1/fgt/FGT60D461xxxxxxx/api/v2/monitor/fortiguard/service-communication-stats

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