API [FortiMail Workspace Security]

Important: This page describes the FortiMail Workspace Security API. For details about the FortiMail Browser Security API, see API [FortiMail Browser Security only].

This page includes the following topics:

About the FortiMail Workspace Security API

The FortiMail Workspace Security API enables scanning of files and URLs to detect whether they are malicious or clean. You can also use the API to perform many other functions, such as changing the verdict of a scan, requesting a FortiMail Workspace Security IR Team investigation of a scan, or releasing an email from quarantine.

Note: Before implementing any of the FortiMail Workspace Security API functionality, contact your Customer Success Manager for FortiMail Workspace Security to make sure that the API functionality is included in your license.

API URL format

In this Documentation Center, APIs are presented with the following format:

GET /api/v1/xxx/yyy/

- or -

POST /api/v1/xxx/yyy/

- or -

PUT /api/v1/xxx/yyy/

It is necessary to add the "https://<PERCEPTION-POINT-URL>" prefix to each of the APIs, where <PERCEPTION-POINT-URL> is:

  • For US environments

api.perception-point.io

  • For EU environments

api.eu.perception-point.io

  • For AUS environments

api.aus.perception-point.io

This creates the full format of the required APIs, such as:

  • For US environments

GET https://api.perception-point.io/api/v1/xxx/yyy/

  • For EU environments

GET https://api.eu.perception-point.io/api/v1/xxx/yyy/

  • For AUS environments

GET https://api.aus.perception-point.io/api/v1/xxx/yyy/

  1. In FortiMail Workspace Security, go to Settings > Account.

  2. The Environment of your organization will appear under General > Info: US, EU, or AUS.

API Authentication

The request HEADERS for all API calls must contain an authorization token:

  • Header Key: "Authorization"

  • Header Value: "Token <TOKEN_VALUE>"

Example

inherit 
response = requests.post(
    "https://<PERCEPTION-POINT-URL>/someAPI/",
    headers={"Authorization": "Token <TOKEN_VALUE>"},
)

print response

{"scan_id": 123456}

Each FortiMail Workspace Security admin user - that has an Admin user-role - has an associated API token. Admin users that don't have the Admin user-role do not have an associated API token.

  • The API authentication token is sometimes referred to as the API key.

  • Each token relies on the associated user constantly being a valid admin user in FortiMail Workspace Security.

    Tip:

    If you don't want to be dependent on a specific user constantly being part of the organization [and not leaving], then you can create a dedicated admin user for this purpose. For example, you could create an admin user with the user name "Dedicated API user."

    Make sure to assign the new user the "Admin" role. To access the API authentication token for the new dedicated admin user, you'll need to sign-in to FortiMail Workspace Security as the new dedicated user. For additional details, see API Key.

For details on how to get an API authentication token, see API Key.

API throttling and retry

Throttling is based on the commercial agreement, with a default maximum of 100 API calls per minute. If you exceed this amount, you'll get error code 429, and you'll need to implement a retry mechanism in order to maintain the queue.

Flow chart diagram

API catalog

You can find information about the following APIs:

See also: