FortiCWP service endpoints supports HTTP requests through the use of REST APIs. This section contains documentation for FortiCWP REST API service endpoints. FortiCWP provides one endpoint with single authentication token to simplify developer experience. All the service endpoints can be accessed through a single access/bearer token. The HTTP requests provide access to valuable FortiCWP cloud resources. All FortiCWP REST APIs, such as Get, POST, etc. require access/bearer token in assembling HTTPS requests.
There are 2 methods of acquiring the access/bearer token from FortiCWP to assemble a REST API request to access FortiCWP resources.
Client credential can be used to generate access/bearer token to form request headers. First, you will need to log into FortiCWP and generate a FortiCWP credential, please follow the guide in Generate Credentials to generate a credential. This is only a one-time process, and only one credential is necessary to generate access/bearer token.
After you have acquired a client credential, it can be used permanently to assemble the request header to obtain an access/bearer token as long as the client credential is not revoked.
Follow the example in Get Credentials Token to use client credential to assemble HTTPS POST request header to acquire access/bearer token.
The use of refresh token requires the credential token above. Once you get the response through client credential, you may use the refresh token in the response body to acquire more bearer tokens without using client credential.
Follow the example in Get Refresh Token to generate access/bearer token using refresh token. The refresh token will expire 8 hours after generated.
After acquiring access/bearer token, use the bearer token to assemble a REST API request. Like all other REST APIT requests, FortiCWP operate through a secured channel: URI request with HTTPS protocol. The details of the request parameters are determined by the specific REST API specification.
You may take a closer look in each REST API specification to determine what additional fields are necessary to fulfill the request. Request body is an optional field, depending on the API specification, some parameters may be required and others are optional.
There are 5 request headers that are often used in FortiCWP REST API requests. The first 3 are default request headers.
|Host||The domain name of the REST service endpoint or the IP address|
|Access/bearer token generated earlier through one of the get token methods|
|Content-Type||This default header is set as "application/json"|
|Company ID||The company ID of the company which the username or the credential is originated from. Company ID can be obtained from Get Resource Map|
File ID is used when requests sent associate with documents stored in the cloud accounts. File ID can be obtained from Get Alert by Filter
When you have assembled the request header and body, the request is ready to be sent to the REST endpoint. Here is a GET request example in HTTPS:
GET /api/v1/country/list? HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzY29wZSI6IkFQSSIsImlzcyI6ImZhdXRoLXNlcnZlciIsImhvc3QiOlsiRkNXUCJdLCJleHAiOjE1ODY5MTUxNjQsImFpZCI6InFhLmNhc2IxQGdtYWlsLmNvbSJ9.Hh2yVHEEd73BJ31rEjB2C-iclodmMigEPIwtuRwCObo
After you sent the request to FortiCWP service endpoint, you will receive a response header and a response body. The above request calls for the list of countries, and here is a part of the response in JSON format:
"country":"United States of America"
API throttling refers to the limit that FortiCWP sets on the number of requests in a range of time to prevent the application sending too many requests. The API throttling of FortiCWP is 100TPM (times per minute), meaning there can have 100 requests in one minute.