Audit Trail API

Why use Audit Log API

The Audit Log API allows tracking important actions done in MadKudu Admin app to understand who accessed it, when and why.

It captures in real-time a list of actions occurring within the MadKudu app in the last 13 months. It includes a history of data to

• See who is logging into your organization account

• See who added users

• View actions taken by specific users

• Identify and prevent misuse of any organization resources.

Who should use the Audit Log API

The Audit Trail API is typically meant for systems admins and 3rd party accounts who need to in monitor their users actions in MadKudu account for security purposes.

How to use the Audit Log API

This Audit Trail API is accessible through MadKudu's API https://api.madkudu.com. It only supports a subset of all possible MadKudu audit events

Pre-requisite

• Your a MadKudu Admin

• To authenticate, first get your MadKudu API key on https://app.madkudu.com > Integrations > API

Authentication

Please follow instructions in the API documentation: https://developers.madkudu.com/

The base URL for accessing the Audit Trail API methods is https://api.madkudu.com/v1/audit. All of the endpoints detailed below branch from this base URL.

The Audit Trail API will return a list of events in a JSON format.

Audit trail routes

Use the following route to access methods from Audit Trail API

• GET /v1/audit retrieve all audit events from your account

• The following filters can be applied in order to narrow the range of actions returned. Filters are added as query string parameters and can be combined together. Multiple filter parameters are additive (a boolean AND) and are separated with an ampersand (&) in the query string. Filtering is entirely optional.

• Filter	Type	Description
  from	date	format date YYYY-MM-DD
  to	date	format date YYYY-MM-DD
  event	string	name of the action performed by the user. please refer to What events are tracked list to get the name of the event you are looking for.
  user	string	email address of the user

The result displays events by the most to least recent ones.

• GET /v1/audit/:eventId

Examples of queries you may want to use:

1. Get the full list of activity on your account

   GET /v1/audit

2. Get the list of users who logged in a given timeframe

   GET /v1/audit?event=logged-in&from=date&to=date In the following example, you would receive all of the login events between 2021-06-01 and 2021-06-30. https://api.madkudu.com/v1/audit?event=logged-in&from=2021-06-01&to=2021-06-30

3. Get the list of activities of a specific user

   GET /v1/audit?user=name@domain.com

The audit event

Every audit event logged by the Audit Trail API includes:

• id: the event id

• tenant: your account number

• name: the name of the action performed, identified by a string from the known list of actions (ex: Logged in, Logged out)

• feature: the environment where the action is performed. Here the MadKudu (general) App with metas (context)

• created_at: the date and time (with timezone) of the action performed (UTC timezone)

• sent_at: the date when the event was effectively sent

• received_at: the date when the event was effectively received for ingestion

• user_email: the user performing the action, identified by their email address

Example:

{
  "events": [
    {
      "id": "46989615-30a5-49c7-997b-65ddcd24d61c",
      "tenant": 3327,
      "name": "logged-in",
      "feature": {
        "name": "general",
        "metas": {}
      },
      "created_at": "2021-05-23T14:03:46.000Z",
      "sent_at": "2021-05-20T14:03:46.716Z",
      "received_at": "2021-05-22T14:03:46.000Z",
      "user_email": "yoann@madkudu.com"
    }
  ]
}

Events tracked

Below is the list of the currently supported audit events tracked in the app for which you can get a complete history (for all the account, per event or per user)

activated-integration
added-credit-card
added-new-user
asked-for-password-reset
completed-oauth
deactivated-integration
logged-in
logged-out
reset-password
signed-up
started-oauth