Audit Log examples
Testing the audit logs endpoint, with examples.
The audit logs endpoint provides detailed logging information and large amounts of data. The following examples step through some audit logs use cases to explain how the parameters function.
How to use these examples
Each use case below contains an example using the Mural developer portal API reference.
Along with the walkthrough steps, you can click the tabs at the top of the example window to view the generated code in different languages. You'll find example code in cURL, Node, Ruby, Javascript, and Python.
Note: You’ll need to use a valid API key to follow these examples and generate a response. See Create API keys for more information.
Limit results to a specific number of entries
By default, the audit logs endpoint provides the most log entries, up to 50,000 per response. But, we can limit responses to get manageable results.
The maxResults
parameter returns the specified number of audit log entries in the response. Valid maxResults
requests are 1–50000.
To retrieve more than 50000 entries, we use nextToken to paginate responses across multiple requests. See Use tokens to request additional data.
Example: Retrieve last 50 entries
By setting maxResults
to 50, we retrieve only the latest 50 entries.
Example request
curl --request GET \
--url 'https://api.mural.co/enterprise/v1/audit-log?maxResults=50' \
--header 'Accept: application/json' \
--header 'Authorization: apikey YOURAPIKEY'
Example response
{
"data": [
{
"action": "UPDATE_COMPANY_SSO",
"actor": {
"company": "MURAL",
"email": "[email protected]",
"id": "exampleId",
"name": "Integrations Example User",
"type": "USER"
},
"date": "2022-02-01T22:19:42.841Z",
"id": "node-8ae0c784e3e11697b0850c80129ad26b-44d3386d-788e-4da4-9afa-2814cb54cd12",
"ip": "126.33.94.213",
"snapshotDate": "2022-02-01T23:59:59.999Z",
"affected": {
"company": "muraltestenterprise",
"email": null,
"id": "muraltestenterprise",
"name": null,
"type": "COMPANY"
}
},
//additional 49 records
],
"nextToken": "eyJleGVjdXRpb25...BUm9vMVVRPT0ifQ=="
}
Test this example
- In the API reference, click Audit Logs on the left.
- Scroll down to the "Try It" section.
- Next to the Try It button, click the authentication icon.
- In the Authorization box, enter
apikey
followed by a space and your API key. - In the maxResults field, enter 50.
- Click Try It.
The API generates a server response of 200 OK with additional JSON output. Click the sections to expand or collapse them.
You should see 50 audit log entries in the response data.
Filter results by date
Use the filter[date][since]
and filter[date][until]
parameters to limit the response to a specific date range.
Dates are in UTC timezone, and use the format (yyyy-mm-ddTHH:mm:ssZ).
Example: Only show entries since a certain date
Here, we can limit the results to only show actions starting on a certain date.
Example request
curl --request GET \
--url 'https://api.mural.co/enterprise/v1/audit-log?filter\[date\]\[since\]=2022-02-01' \
--header 'Accept: application/json' \
--header 'Authorization: apikey YOURAPIKEY'
Test this example
- In the API reference, click Audit Logs on the left.
- Scroll down to the "Try It" section.
- Next to the Try It button, click the authentication icon.
- In the Authorization box, enter
apikey
followed by a space and your API key. - In the filter[date][since] field, enter a start date.
- Click Try It.
The API generates a server response of 200 OK with additional JSON output. Click the sections to expand or collapse them.
Verify the earliest entry in the response (at the bottom) matches your since date. Remember, audit logs display in reverse chronological order, and contain up to 30 days of entries. If you don’t define a specific time range using the filter[date][since]
and filter[date][until]
fields, the API returns events from the past 7 days. Over 120 events can be logged.
Example: Only show entries within a date range
Let’s show entries between two dates. We’ll use both filter[date][since]
and filter[date][until]
to achieve this.
Responses are limited to a maximum range of 30 days. If you don’t define a specific time range using the filter[date][since]
and filter[date][until]
fields, the API returns events from the past 7 days.
Example request
curl --request GET \
--url 'https://api.mural.co/enterprise/v1/audit-log?filter\[date\]\[since\]=2022-02-01&filter\[date\]\[until\]=2022-02-02' \
--header 'Accept: application/json' \
--header 'Authorization: apikey YOURAPIKEY'
Test this example
- In the API reference, click Audit Logs on the left.
- Scroll down to the "Try It" section.
- Next to the Try It button, click the authentication icon.
- In the Authorization box, enter
apikey
followed by a space and your API key. - In the filter[date][since] field, enter a start date.
- In the filter[date][until] field, enter a end date.
- Click Try It.
The API generates a server response of 200 OK with additional JSON output. Click the sections to expand or collapse them.
Verify that the entry at the top of the output is no later than your until date. The last entry in the output should be no earlier than your since date. Remember, audit logs display in reverse chronological order, and contain up to 30 days of entries. If you don’t define a specific time range using the filter[date][since]
and filter[date][until]
fields, the API returns events from the past 7 days.
Use tokens to request additional data
The response limit is 50,000 entries. To retrieve more than 50,000 sequential results, we can use the nextToken
parameter to paginate responses across a few requests.
What is a token?
Every audit logs response concludes with a token. A token is a long string of characters that serves as a unique bookmark to our current result set.
Tokens appear at the very end of every audit logs response, and look like this:
"nextToken": "eyJfi0TPn9mT4AHWqtCR...CZJ52bpRXdjVGelQ=="
How does a token work?
Think of using a token like placing a marker. We use this imaginary marker every 50,000 pages to locate “the next 50,000 pages” of information.
By using this token in our next API call, the API remembers where the last response ended. It continues its response to our previous request, starting with the next set of data. And it puts a token at the end of the new request, in case we’d like to continue even further.
Example: Use a token to paginate large responses
What if we want to retrieve much more than 50,000 results?
In this first example, we’ll do a simple audit log dump, and take everything we can. Well, up to three requests worth of data, anyway—around 103,000 entries.
Example request
curl --request GET \
--url 'https://api.mural.co/enterprise/v1/audit-log?maxResults=50000&nextToken=eyJleGVjdXRpb25...BUm9vMVVRPT0ifQ==' \
--header 'Accept: application/json' \
--header 'Authorization: apikey YOURAPIKEY'
Test this example
- In the API reference, click Audit Logs on the left.
- Scroll down to the "Try It" section.
- Next to the Try It button, click the authentication icon.
- In the Authorization box, enter
apikey
followed by a space and your API key. - Clear all fields.
- Click Try It.
The API generates a server response of 200 OK with additional JSON output. Click the sections to expand or collapse them.
At the end of the response, we are provided with a token:
"nextToken": "eyJfi0TPn9mT4AHWqt...HRqhUQVJjcDticz5=="
We’ll use this token in our next sequential API call to continue the responses where we left off.
To continue the previous response
- At the end of the previous response output, locate the token.
- Copy the token, excluding the start and end quotes.
- In the nextToken field, paste the token.
- Click Try It.
At the end of this second response is another token, which can use in a third request to pull down the third set of data. And so on, and so forth.
Any fields other than
maxResults
are ignored when we use anextToken
field.
Example: Use a token to paginate smaller response sets
We can also use tokens to continue parsing smaller sets of data.
For example, if we want to view every time the ACCEPT_MEMBERSHIP
action occurred, but limit our responses to sets of 25, we can do so using tokens.
Here, we can show all ACCEPT_MEMBERSHIP
entries, 25 at a time.
Test this example
- In the API reference, click Audit Logs on the left.
- Scroll down to the "Try It" section.
- Next to the Try It button, click the authentication icon.
- In the Authorization box, enter
apikey
followed by a space and your API key. - In the maxResults field, enter 25.
- In the filter[action] field, enter the action ACCEPT_MEMBERSHIP.
- Click Try It.
The API generates a server response of 200 OK with additional JSON output. Click the sections to expand or collapse them.
At the end of the response, we are provided with a token that looks something like this:
"nextToken": "eyJleGVjdXRpb25...BUm9vMVVRPT0ifQ=="
We’ll use this token from the response with the first 25 results set to continue with another 25 results from the same set.
To continue the previous response
- At the end of the previous response output, locate the token.
- Copy the token, excluding the start and end quotes.
- In the nextToken field, paste the token.
- Click Try It.
Any fields other than
maxResults
are ignored when we use anextToken
field.
Filter results by action
Each entry in the audit log is an action and the action’s details.
As you can imagine, there are many available actions in an audit log. If we know what we’re looking for, we can filter by a specific action to show only the log entries with that action. We can filter by one action at a time.
Example: Show all events where a new mural was created
First, we’ll request audit log entries for the action CREATE_MURAL. Since we aren’t setting a specific time range using the filter[date][since]
and filter[date][until]
fields, the API returns events from the past 7 days.
Example request
curl --request GET \
--url 'https://api.mural.co/enterprise/v1/audit-log?filter\[action\]=CREATE_MURAL' \
--header 'Accept: application/json' \
--header 'Authorization: apikey YOURAPIKEY'
Test this example
- In the API reference, click Audit Logs on the left.
- Scroll down to the "Try It" section.
- Next to the Try It button, click the authentication icon.
- In the Authorization box, enter
apikey
followed by a space and your API key. - In the filter[action] field, enter the action CREATE_MURAL.
- Click Try It.
The API generates a server response of 200 OK with additional JSON output. Click the sections to expand or collapse them.
If you scroll through the response data, you can see that every action is a CREATE_MURAL action.
Example: Show the last 25 sign-in failures
We can make our results more relevant to what we want to know by combining the action filter with maxResults
. This test will show us who couldn’t sign in, but limit the return to 25 entries.
Test this example
- In the API reference, click Audit Logs on the left.
- Scroll down to the "Try It" section.
- Next to the Try It button, click the authentication icon.
- In the Authorization box, enter
apikey
followed by a space and your API key. - In the maxResults field, enter 25.
- In the filter[action] field, enter the action SIGN_IN_FAILURE.
- Click Try It.
Example: Show all LEAVE_WORKSPACE events after 1 January, 2021
Let’s say we want to know which members left a workspace after the holidays. This test displays all LEAVE_WORKSPACE actions occurring after 1 January, 2021.
Test this example
- In the API reference, click Audit Logs on the left.
- Scroll down to the "Try It" section.
- Next to the Try It button, click the authentication icon.
- In the Authorization box, enter
apikey
followed by a space and your API key. - In the filter[action] field, enter the action LEAVE_WORKSPACE.
- In the filter[date][since] field, enter 2021-01-01.
- Click Try It.
The API generates a server response of 200 OK with additional JSON output. Click the sections to expand or collapse them.
If you scroll through the response data, you can see that every action is a LEAVE_WORKSPACE action, with the date of each action occurring on or after January 1.
Updated about 1 month ago