4 min read

Feature

Using the Audit Log API, the account admin is able to pull Audit Log events happening in a monday.com account. Monitoring the data displayed here can help to protect against unwanted account access, investigate any suspicious behavior, and ultimately, to ensure the safe use of the account at all times.

The Audit Log API can be used to:

Identify potential security issues or unwanted access attempts
Transfer Audit Log event data into a different auditing platform, such as a SIEM, for further analysis
Create custom-built applications to further understand how the monday.com account is being used

Note: This advanced security feature is available on the Enterprise plan and can only be accessed by the account admin.

Generating the API token

To generate the audit log API token, access the admin section of your account, click into the "Security" section and then the "Audit" tab. From there, select on the "Monitor by API" button and copy it to your computer as so:

How to use it

The Audit Log API is REST API that uses the GET HTTP verb both to query and retrieve events’ data. The return methods will also return standard HTTP status codes to indicate success (or failure).

The rate limit is up to 50 requests per minute.

Base URL

The base URL for accessing the Audit Logs API methods is https://<YOUR_DOMAIN>.monday.com/audit-api/get-logs

Note: Replace <YOUR_DOMAIN> above with your account URL name (if your account URL is myaccount.monday.com, you would write "myaccount" here).

Bearer token

Accessing the Audit Log API can only be done with a token generated by the account’s admin.

As the account admin, click on your profile picture in the bottom left corner and select "Admin". From the Security tab of the admin section, click on "audit" and then "Monitor by API".

From here, click to generate and copy the token. Use the token in the authorization header, as type bearer.

Authorization header

Here’s an example of an authorization header:

curl -g -X GET -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJ0aWQiOjQsInVpZCI6MywiaWFkIjoiMjAyMS0wOC0xMFQxNzowOTozNC40NjNaIiwicGVyIjocdadsc6YXBpIiwiYWN0aWQjk32rkjhduIjoibG9jYWwtcmVnaW9uIn0.RqPFKVGzxxUsqZ5V3hU-aAv4Kmkxyp39-L60DSG6mfw' 'https://myaccount.monday.com/audit-api/get-logs?page=1&per_page=20'

Filtering the Audit Log API

The following attributes can be used to filter the Audit Log API:

user_id
event
ip_address
start_time
end_time (specify time format)

In order to filter you should add the filters to the query as parameters.

Here’s an example of a filtered query (retrieves logs created after "2021-08-24T17:03:00Z"):

Example

Query:

Returned data:

{
  data: [
    {
      "timestamp": "2021-08-24T17:18:39Z",
      "account_id": 739628,
      "user_id": 27,
      "event": "delete-board",
      "slug": "myaccount",
      "ip_address": "123.123",
      "user_agent": "user agent",
      "client_name": "Chrome",
      "client_version": "92.0.4515.160",
      "os_name": "Mac OS",
      "os_version": "10.0.0",
      "device_name": null,
      "device_type": "desktop",
      "activity_metadata":  {
        "board_name": "My projects"
      }
    }
  ],
  page: 1,
  per_page: 20,
  next_page: null
}

Status codes

The following status codes will be returned for each request:

200 - retrieving the audit logs succeeded
400 - client errors (e.g. invalid filter)
401 - unauthorized (e.g. requests without a token/invalid token)
429 - rate limit error
500 - internal server error

Description of Audit Log events

Looking to understand more about what each Audit Log event actually means for your account? We've got you covered! Check out the following board or look below to learn more about each of the Audit Log events that we offer.

If you have any questions, please reach out to our team right here. We’re available 24/7 and happy to help.