About the Audit Log API
Understanding the information presented in audit logs.
Overview
Mural’s audit logs provide a detailed account of your company’s activity, including what actions occurred, who performed them, and how those actions affected other parts of the company. Use the audit logs endpoint to learn more about how your employees use Mural. Currently, 120 events can be logged by the audit log.
This article breaks down the details of the audit logs, explaining each type of data represented.
Current audit logs limitations
Audit logs are not real time. Audit log events are made available within 24–48 hours. If you make a request and the time range overlaps with the last 24–48 hours, you may not see all events during this time frame.
We do not display all known information in the audit log. Our intention is to provide administrator-level data that informs, promotes exploration, and assists with troubleshooting.
To ensure a high quality experience for all users and to prevent abuse and security issues, the Mural audit log API enforces a rate limit of 1,500 calls per day per customer, roughly translating to around 1 call per minute.
The action filter allows for the input of a maximum of 10 actions, which should be provided as a list separated by commas.
We limit the API response to a maximum range of 30 days. If you don’t define a specific time range using the
filter[date][since]
andfilter[date][until]
fields, the API returns events from the past 7 days.
Audit log entries
Audit logs provide details on actions your company performed. Each log entry is a single action event. Actions are performed by entities and affect other entities.
Audit log entries display in reverse chronological order, with the newest entries shown first.
Each entry describes the action and the entity that performed it. Entries also include affected entities, timestamps, IP addresses, and user email addresses.
Here’s a sample audit log entry for a CREATE_MURAL action:
{
"action": "CREATE_MURAL",
"actor": {
"company": "Galactic Empire",
"email": "[email protected]",
"id": "ub53bc609c33ca58979ball32",
"name": "Darth Vader",
"type": "USER"
},
"date": "1977-05-25T19:00:05.662Z",
"id": "unode-28580686c751-739a-bd94-2045-72565b33-285eb5add71e20bff7bcl9f948be5907",
"ip": "10.1.1.38",
"snapshotDate": "1977-05-25T23:59:59.999Z",
"affected": {
"company": "Galactic Empire",
"email": null,
"id": "askywalk20.1138555370665473",
"name": null
"type": "MURAL"
},
"destination": {
"company": ""Galactic Empire"",
"email": null,
"id": "1456859873578",
"name": null,
"type": "ROOM"
}
},
Each audit log entry contains the following pieces:
- action: The log event, or the activity that happened. Action names are in uppercase, like CREATE_MURAL.
- group attribute: Every action has at least one group attribute based on the entity that took action or was acted upon. Group attributes are clusters of nested JSON.
- attribute: A single attribute contains a string, like an IP address.
- entity: An entity is an object that either performs or is affected by an action. The entity defines each group attribute’s type. Entities are in uppercase, like WORKSPACE.
- string: The data for an attribute. For example, the string for an email attribute is an email address.
Audit logs details
In this section, we provide more detail for each piece of the audit logs.
Actions
Each audit log entry is an action and its related data. The action is the topmost item in our JSON hierarchy.
Some example actions and their definitions:
- CREATE_MURAL: A mural was created.
- SUSPEND_USER: A member (user) account was suspended.
- LEAVE_WORKSPACE: A member left a workspace. ¡Adios!
Examples
SIGN_IN
A SIGN_IN action is short. It contains an actor
group attribute (with nested data) and some single attributes (date
, id
, ip
).
In the example below, we see all the details when Mr. Coyote signed in on November 16.
{
"action": "SIGN_IN",
"actor": {
"company": "ACME",
"email": "[email protected]",
"id": "a3bcdua4608b42b5defea9733",
"name": "Wile E. Coyote",
"type": "USER"
},
"date": "2020-11-16T11:16:16.730Z",
"id": "node-c11fcb9e8-983-7f3-33fa1-9835cd1013c2d26b1c7581f4ea56b49-a9391ae6b2609",
"ip": "192.168.1.8"
"snapshotDate": "2020-05-16T23:59:59.999Z"
},
The actor
group attribute contains the actor’s:
company
nameemail
address- unique
id
- given
name
At the bottom of the actor
group attribute is the entity type
of USER.
INVITE_MEMBER
Some action types contain many group attributes and are larger entries in the audit log. The INVITE_MEMBER action includes group attributes for the:
actor
who did the invitingaffected
inviteedestination
mural, to which the invitee was invited
In this example, we see Mr. Coyote at ACME invited the member, Ms. Runner, to take part in an ACME mural.
{
"action": "INVITE_MEMBER",
"actor": {
"company": "ACME",
"email": "[email protected]",
"id": "a3bcdua4608b42b5defea9733",
"name": "Wile E. Coyote",
"type": "USER"
},
"date": "2020-11-16T22:55:18.815Z",
"id": "node-750a9095d2b-998900ab61b563ebb97-c4b-596-dae48954e7678df6c5b0-41822bd1",
"ip": "192.168.1.8",
"snapshotDate": "2020-11-16T23:59:59.999Z",
"affected": {
"company": "Beep Beep",
"email": "[email protected]",
"id": "rrunner09161950",
"name": "Road Runner",
"type": "USER"
},
"destination": {
"company": "ACME",
"email": null,
"id": "murally-org.1605000999221",
"name": null,
"type": "MURAL"
}
},
The actor
(who took the action) is Mr. Coyote. The affected
party is a USER, “Road Runner.” The destination
, where the affected
was invited, is an entity type
of Mural.
Group attributes
Group attributes are the clusters of metadata that define each action. Each group attribute is made up of some (single) attributes and an entity type. Group attributes can be: actor
, affected
, origin
, and destination
.
Depending on the action, not every type of group attribute is used.
Group attribute | Description |
---|---|
actor | The entity that performed the action. |
affected | The entity that was affected by the action. |
destination | The target location of the affected entity. |
origin | The source location of the affected entity. |
Example
We can see this actor
group attribute contains nested single attributes. These attributes give us information about the actor: email
address, name
, unique id
, and so forth.
"actor": {
"company": "ACME",
"email": "[email protected]",
"id": "a3bcdua4608b42b5defea9733",
"name": "Wile E. Coyote",
"type": "USER"
},
Single attributes
While a group attribute is a cluster of data, a single attribute is a variable name containing a string. This table shows the single attributes you can find in the audit logs.
Single attribute | Description |
---|---|
action | The type of action performed. See the full list of available actions in the API Reference. |
company | The company name that the entity belongs to. |
The email address of the entity. | |
date | The date and time when the action occurred. We format dates like 1985-10-26T01:20:00Z . |
id | A unique identifier. The format of an id varies depending on what it defines, such as an actor, an action, or a room. An actor’s USER id might be jadams002 , whereas a destination id for a ROOM might be 1598387911389 . |
ip | The source IP address of the requesting entity. |
name | The given name of the entity. |
snapshotDate | The date the data was extracted. |
Entities
Group attributes are defined by their entity type. The entity is an object that either performed an action or was affected by an action.
For example, the entity type for a destination might be Mural, because the location that was affected was … a mural.
Entities are in uppercase, like WORKSPACE.
The list of possible entities is APIKEY
, BILLING_GROUP
, COMPANY
, EMAIL
, HUB
, MURAL
, REFCODE
, ROOM
, SLACK_COMMAND
, TEMPLATE
, USER
, WORKSPACE
.
Hidden items
You may encounter hidden or masked information when reviewing audit logs. Masked information is indicated by a series of asterisks (****) in place of data.
This indicates that the information belongs to a user that is not part of your company. Certain information between companies is masked to retain corporate privacy.
Let's consider an example of a user (Jenny) from one company (OUR_COMPANY) deleting the mural in a workspace associated with another company (OTHER_COMPANY). The snippet below provides an example of what the audit log API response would look like for an API user at OUR_COMPANY, as the mural ID belonging to OTHER_COMPANY is masked.
{
"action": "DELETE_MURAL",
"actor": {
"company": "OUR_COMPANY",
"email": "[email protected]",
"id": "uc336f92ba69cc975f06c5979",
"name": "Jenny Employee",
"type": "USER"
},
"date": "2021-07-15T15:13:03.635Z",
"id": "node-ca554f6f81fb-7a5b-f0d4-3a5c-161839f4-82342d1a6ce82487baee4c27f4c6134c",
"ip": "127.0.0.1",
"snapshotDate": "2021-05-30T23:59:59.999Z",
"affected": {
"company": "OTHER_COMPANY",
"email": null
"id": "*********************************",
"name": null
"type": "MURAL"
},
"destination": {
"company": "OTHER_COMPANY",
"email": null
"id": "1621027536887",
"name": null
"type": "ROOM"
}
},
Updated about 1 month ago