API Access
The FortiLAN Cloud REST APIs provide functions similar to its GUI functions for configuration and monitoring. For details, see FortiLAN Cloud REST APIs. To access FortiLAN Cloud, a client sends secure HTTP requests to the FortiLAN Cloud API URL determined by the domain region.
|
Domain |
API URL |
|---|---|
| Global |
https://www.fortilan.forticloud.com/api/v1/ |
| Europe |
https://eu.fortilan.forticloud.com/api/v1/ |
| Japan |
https://jp.fortilan.forticloud.com/api/v1/ |
All API requests and responses are in JSON format. The client programs need to use these HTTP headers; Content-Type: application/json and Accept: application/json.
Users and Authentication
Authentication (providing credentials and obtaining access token) is performed for Email users, IAM users, and API users with either FortiLAN Cloud or an external Fortinet entity, FortiAuthenticator.
|
Users |
Authentication |
|---|---|
| Email users & IAM users |
Authentication using FortiLAN Cloud with the following API path.
|
| API users |
Authentication using FortiAuthenticator with the following API path.
|
The obtained access token must be sent as bearer token header in FortiLAN Cloud APIs; Authorization: Bearer $access_token.
Email Users
The Email users can be used to authenticate with FortiLAN Cloud and obtain access token with the following web call (Global domain is used in this example).
Request
$ curl https://fortilan.forticloud.com/api/v1/auth -H 'Content-Type: application/json' -d '{"accountId":"acct1@example.com","userName":"user1@email.com","password":"1234"}'
Response
{\"access_token\": \"rVDBFKWu72Jvafj1FcVgIUXoTaNV99jU\",\"expires_in\": 1593739101}
In the request, the accountId is the primary account email address and the userName is either the primary or the sub-user email address. For a sub-user created account, ensure that the user is created with Admin role instead of Regular role. Only primary account and its Admin users can use the APIs.
Invalidate the access token after it is no longer required as displayed in this example.
$ curl https://fortilan.forticloud.com/api/v1/auth/invalidate_token -H 'Content-Type: application/json' -H 'Authorization: Bearer $access_token' -d '{ "access_token": "$access_token" }'
IAM Users
The IAM users can authenticate with FortiLAN Cloud and obtain access token with the following web call (Global domain is used in this example).
Request
$ curl https://fortilan.forticloud.com/api/v1/auth -H 'Content-Type: application/json' -d '{"accountId":"acct1@example.com","userName":"user2","password":"1234", "type":"iamuser"}'
The type parameter is to be set to iamuser. If this parameter is not provided then it defaults to emailuser.
Ensure that the IAM user is created with Admin role for FortiLAN Cloud portal. Invalidate the access token after it is no longer required as for Email users in the preceding section.
API Users
API users authenticate with FortiAuthenticator to obtain the access token, this token is then used with FortiLAN Cloud.
Perform these steps to obtain access token from FortiAuthenticator.
- Login into the FortiCloud IAM portal with the account credentials.
- Create an API user and set Admin permission for FortiLAN Cloud.
- Download the API credentials (API ID, Password and Client ID).
Use the downloaded API user credentials to obtain the access token from FortiAuthenticator.
Request
$ curl https://customerapiauth.fortinet.com/api/v1/oauth/token/ -H 'Content-Type: application/json' -d '{\"username\": \"$api_id\", \"password\": \"$password\", \"client_id\": \"fortilancloud\", \"grant_type\": \"password\"}'
Response
{
\"access_token\": \"paLreKW6YGDfgSUfreEH90UCc1915v3\",
\"expires_in\": 14400,
\"message\": \"successfully authenticated\",
\"refresh_token\": \"WpD0HVYUdshsiWlMBR0Q6uUoV2TGUIa\",
\"scope\": \"read write\",
\"status\": \"success\",
\"token_type\": \"Bearer\"
}
The FortiAuthenticator access token is then used with FortiLAN Cloud by including it in the bearer header like the Email and IAM users.
To refresh an expired or non-expired access token
$ curl https://customerapiauth.fortinet.com/api/v1/oauth/token/ -H 'Content-Type: application/json' -d '{\"client_id\": \"fortilancloud\", \"grant_type\": \"refresh_token\", \"refresh_token\": \"WpD0HVYUdshsiWlMBR0Q6uUoV2TGUIa\"}'
To revoke access token
$ curl https://customerapiauth.fortinet.com/api/v1/oauth/revoke_token/ -H 'Content-Type: application/json' -d '{\"client_id\": \"fortilancloud\", \"token\": \"paLreKW6YGDfgSUfreEH90UCc1915v3\"}'
Note: The API user can have only one access token active at a time. In case of multiple concurrent scripts, you are required to create multiple API users with unique user credential to use in each script. Using the same API user to obtain another access token will automatically invalidate previous active access token.
Calling APIs
All APIs require access token be included as bearer authentication. This is an example to query FortiAPs deployed in various logical networks in an account:
$ curl -H "Authorization: Bearer $access_token" https://www.fortilan.forticloud.com/api/v1/inventory/deployed/
This is an example to query all networks existing in an account.
$ curl -H "Authorization: Bearer $access_token" https://www.fortilan.forticloud.com/api/v1/networks/
API Limit
The following limits apply to FortiLAN Cloud APIs.
- From the same source IP address, 6 auth requests are accepted per minute and across different source IP addresses, 60 auth calls are accepted per minute.
- From the same source IP address, 60 other API calls are accepted per minute and across different source IP address, 600 other API calls are accepted per minute.