API - Audit log

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.

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. copy-scan-to-demo

  7. create-new-organization-domain

  8. delete-email-from-inbox

  9. delete-user

  10. disable-decision

  11. django-admin

  12. download-scans

  13. download-scan-sample

  14. enable-decision

  15. export-scans

  16. handle_case

  17. handle_event

  18. handle_scan

  19. highlight-scan

  20. login

  21. logout

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

  23. modify-user

  24. organization-change-audit

  25. 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: