API - Audit log

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

This page includes the following topics:

 

About the audit-events API

The audit-events API allows you to generate an "audit log" or an "activity log" - a list of the events that occurred in the FortiMail Workspace Security platform in your organization. You can specify the beginning and the end of the period for which events are included in the list. You can also specify a string that must be included in the event details of each included event.

For authentication requirements, and other details about the Fortinet API, see API Authentication.

For information about viewing an audit log in FortiMail Workspace Security, see Audit log.

Request URL

GET<PERCEPTION-POINT-URL>/api/v1/audit-events/

For additional information about formatting the above endpoint, see API URL format.

  • For US environments:

https://api.perception-point.io

  • For EU environments:

https://api.eu.perception-point.io

  • For AUS environments:

https://api.aus.perception-point.io

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

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

Available GET query fields

Field name

Field description

Format

Mandatory

start

The unix timestamp that represents the start time of the query. Limits the results to where timestamp >= start

10-digit epoch timestamp

No

end

The unix timestamp that represents the end time of the query. Limits the results to where timestamp <= end

10-digit epoch timestamp

No

_search

Performs a search to find a specified string that is contained in any of the following event fields:

  • username

  • user-email

  • action

  • description

  • instance_id (organization id, scan id, user id, etc.)

String

No

Response options

Parameter

Description

count

The total number of events that are returned in this query.

page_result_count

The number of events that are included in this page.

has_more

Indicates if there are more events on the next page.

next

The url to get the next page of events - or null if this is the last page.

results

The list of events.

Event structure

  • Action

    • type: The event action type. [See Action types below]

    • description: A description of the event.

    • Extra: Additional information about the event.

  • Performing user

    • user: The user that the event belongs to:

      • email

      • name

  • Timestamp

    • The timestamp of the event.

Response pattern

inherit 
{
    "count": <total logs for query>,
    "page_result_count": <total results for this page>,
    "next": <url for next page, or null - if last page>,
    "has_more": false,
    "results": [
        {
            'id': uuid4-string,
            'timestamp': isoformat-timestamp
            'environment': environment-code,
            'performing_user': {
                'organization': number,
                'organization_name': string,
                'user': {
                    'id': number,
                    'name': string,
                    'email': email
                }
            },
            'action': {
                type=action-type (see list),
                description=string,
                target_organization=id,
                target_organization_name=string,
                // Any extra data, if applicable
            }
        }
    ]
}

Response codes

200 OK

Action types

Below are the available action-types, in alphabetic order.

 

Available action types

 

  1. acronis-login

  2. acronis-user-created

  3. add-screenshot-to-blacklist

  4. analyze-sample

  5. changes-monitor

  6. contarct-alert

  7. copy-scan-to-demo

  8. create-new-organization-domain

  9. delete-email-from-inbox

  10. delete-user

  11. disable-decision

  12. django-admin

  13. download-scans

  14. download-scan-sample

  15. enable-decision

  16. export-scans

  17. handle-case

  18. handle-event

  19. handle-scan

  20. highlight-scan

  21. login

  22. logout

  23. malicious-file-reported-by-endpoint,30

  24. modify-user

  25. organization-change-audit

  26. organization-created

  1. organization-domain-deleted

  2. organization-mailboxes-billing-method-changed

  3. organization-number-of-mailboxes-changed

  4. organization-number-of-seats-changed

  5. organization-seats-billing-method-changed

  6. organization-organization-name-changed

  7. organization-organization-type-changed

  8. organization-was-changed-on-organization-domain

  9. protected-user-added

  10. protected-user-changed

  11. protected-user-deleted

  12. release-email

  13. report-sent

  14. request-investigation

  15. rescan

  16. resend-email

  17. resend-user-invitation

  18. saml-token-created

  19. send-user-invitation

  20. setup-email

  21. settings-add

  22. settings-change

  23. settings-delete

  24. update-smtp-record

  25. watch-scan-screenshots

Example

The following example returns all events that:

  • occurred between August 1, 2022, and August 16, 2022 - and that

  • include the name "john"

GET /api/v1/audit-events/?start=1659339780&end=1660635780&_search=john

See also: