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.

• 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] and filter[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 RENAME_MURAL action:

{
  "action": "RENAME_MURAL",
  "actor": { 
    "company": "Galactic Empire",
	"email": "[email protected]",
	"id": "ub53bc609c33ca58979ball32",
	"name": "Darth Vader",
	"type": "USER"
  },
  "date": "1977-05-25 19:00:05.662",
  "id": "unode-28580686c751-739a-bd94-2045-72565b33-285eb5add71e20bff7bcl9f948be5907",
  "ip": "10.1.1.38",
  "affected": {
	"company": "Galactic Empire",
	"id": "askywalk20.1138555370665473",
	"type": "MURAL"
  }

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
• Group attributes
• Single attributes
• Entities

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-16 11:16:16.730",
      "id": "node-c11fcb9e8-983-7f3-33fa1-9835cd1013c2d26b1c7581f4ea56b49-a9391ae6b2609",
      "ip": "192.168.1.8"
    },

The actor group attribute contains the actor’s:

• company name
• email 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 inviting
• affected invitee
• destination 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-16 22:55:18.815",
      "id": "node-750a9095d2b-998900ab61b563ebb97-c4b-596-dae48954e7678df6c5b0-41822bd1",
      "affected": {
        "company": "Beep Beep",
        "email": "[email protected]",
        "id": "rrunner09161950",
        "name": "Road Runner",
        "type": "USER"
      },
      "destination": {
        "company": "ACME",
        "id": "murally-org.1605000999221",
        "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.

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.

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-15 15:13:03.635",
    "id": "node-ca554f6f81fb-7a5b-f0d4-3a5c-161839f4-82342d1a6ce82487baee4c27f4c6134c",
    "ip": "127.0.0.1",
    "affected": {
        "company": "OTHER_COMPANY",
        "id": "*********************************",
        "type": "MURAL"
    },
    "destination": {
        "company": "OTHER_COMPANY",
        "id": "1621027536887",
        "type": "ROOM"
    }
}