Description
This article describes how to retrieve the list of registered units using FortiCare Registration API v3 for IAM users.
Scope
For FortiCare registration API v3.
Solution
Prerequisites for using FortiCare Registration API V3.
The OAuth token is required to access Forticare Registration API V3.
To obtain an OAuth FortiToken:
- An IAM API User must be created through FortiCloud's Identity and Access Management (IAM) portal.
- IAM API users can use their credentials to obtain an OAuth FortiToken from FortiAuthenticator.
This article go through these different steps:
- Creating an IAM API User.
- Requesting an OAUTH FortiToken,
- Using the OAUTH FortiToken to query the FortiCare Registration API v3.
- Create an API User in FortiCloud’s Identity and Access Management.
Before creating the API User, it is necessary to have a Permission Profile with proper permissions.
- In IAM, select Permission Profiles and create a profile named 'FortiCare Registration API' with the permission as described in the following screenshot.
- Use the Add API User wizard to generate API user IDs and passwords.
- Go to Users: the Users pane opens.
- Select 'Add New'/'API User'.
- The Add API User pane opens. Select the following permission profile 'FortiCare Registration API' and add a description.
- On the screen of 'Successful API User Registration', scroll down and select the 'Download Credentials' button.
Caution.
- Downloading API User Credentials will reset the user's security credentials each time this action is performed.
- The downloaded file contains the API Key, Password, and Client ID. A separate Client ID is provided for every portal with allowed access. For this API, the right Client ID is the one for 'Asset Management Cloud' and it normally should be 'assetmanagement'.
-
Request authorization for FortiToken.The IAM API User credentials obtained in 1. must be sent to FortiAuthenticator API at Token.Request query:
$ curl --location --request POST 'https://customerapiauth.fortinet.com/api/v1/oauth/token/' \--header 'Content-Type: application/json' \--data-raw '{"username": "<API Key>","password": "<password>","client_id": "<client_id for FortiGate Cloud>","grant_type": "password"}'
Response:
{"access_token": "7BI7ahcCbIXEMseSSDoXZz8Fl8j315","expires_in": 14400,"message": "successfully authenticated","refresh_token": "2Vxsg5A40qOVnygGuE0f9lCA4w7EjS","scope": "read write","status": "success","token_type": "Bearer"}
Caution:
- Do not forget the trailing slash at Token.
- Use --location in the request to follow redirects.
Once the FortiToken (access_token) is obtained, it should be sent in the Authorization header of all the following requests with Bearer scheme, as in the example below:
Authorization: Bearer 7BI7ahcCbIXEMseSSDoXZz8Fl8j315
-
Query the FortiCare Registration API.It is now possible to use the FortiToken provided to query the Forticare Registration API v3 product lists using the following parameters in the POST body:
{"serialNumber": "FGT90D12345-----","expireBefore": "2019-01-20T10:11:11-8:00","pageNumber": 1}
Parameters.
- serialNumber or expireBefore must be used in the POST body.
- To query all devices, you may use expireBefore with a date in the late future.
Request query:
$ curl --request POST 'https://support.fortinet.com/ES/api/registration/v3/products/list' \--location \--header 'Authorization: Bearer 7BI7ahcCbIXEMseSSDoXZz8Fl8j315' \--header 'Content-Type: application/json' \--data-raw '{"expireBefore": "2026-01-01T10:11:12-8:00"}'Response [redacted]:
{"build": "1.0.0","error": null,"message": "Request processed successfully","status": 0,"token": "7BI7ahcCbIXEMseSSDoXZz8Fl8j315","version": "3.0","assets": [{"description": "","entitlements": [{"endDate": "2017-09-30T00:00:00","level": 5,"levelDesc": "Advanced HW ","startDate": "2013-10-01T00:00:00","type": 1,"typeDesc": "Hardware"},[…]],"isDecommissioned": false,"productModel": "FortiADC VM01","registrationDate": "2014-07-22T04:46:46","serialNumber": "FADV######","warrantySupports": null,"assetGroups": null,"contracts": [{"contractNumber": "################","sku": "FCX-15-00000-247-02-48","terms": [{"endDate": "2017-09-30T00:00:00","startDate": "2013-10-01T00:00:00","supportType": "Hardware"},[…]]}],"productModelEoR": null,"productModelEoS": null}[...]]}
Important Notes on FortiCare API:
API Access Information for V3.
- FortiCare API Base URL: Support.
FortiCare Registration API v3 Resource Base:
- /ES/api/registration/v3/ --> FortiCare Registration API v3 Resources.
- products/list.
- products/register.
- products/details.
- products/description.
- products/location.
- licenses/register.
- licenses/download.
-
Full API documentation can be found on the FNDN website: Fortiner Developer Network.
-
Limits and Quotas.
Maximum 100 calls per minute
Maximum 1000 calls per hour
Maximum 10 errors per hour
Maximum number of units per batch registration is 10
Maximum number of errors allowed per batch registration is 5
