MadKudu offers an Audit Trail API which provides a record of how users of your account are using and interacting with the MadKudu app. The Audit Trail API can be used to provide analysis of how your MadKudu account is being accessed.

Note:

The Audit trail data history began as of June 14, 2021. Only activity tracked after this date is available.
This audit trail is in alpha version accessible through MadKudu's API https://api.madkudu.com. It only supports a subset of all possible MadKudu audit events and will continue to add support for additional audit events.

Who is this for

The Audit Trail API is meant for anyone interested in monitoring audit events in a MadKudu account. This may include security professional monitoring third-party vendor accounts for potential security issues.

What is the Audit Trail

The Audit Trail API captures, in real-time, a list of actions occurring within the MadKudu app in the last 13 months. It includes a self-serve way to access 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.

In order to ensure continued compliance and safeguard against any inappropriate system access.

The Audit Trail API allows to filter for specific actions or users to see who made changes on specific resources in the app. Users only include logged-in users.

How to use the Audit Trail

Pre-requisite

Access to the Audit Trail API requires authentication to https://api.madkudu.com

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

Authentication

The MadKudu API uses HTTP Basic Auth and requires using HTTPS on all API calls.

Your API Key should be used as the basic auth username. You do not need to provide a password.

For example, if your user’s API key was ABCD1234, you need to Base64 encode the string ABCD1234: (Please note the colon at the end) and prepend the string Basic`. In this case, this would result in a final header of:

Authorization: Basic QUJDRDEyMzQ6

The Audit Trail API is read-only and uses a single HTTP verb — GET — to query and retrieve information. These methods will also return standard HTTP status codes to indicate success (or failure).

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:

Get the full list of activity on your account

GET /v1/audit
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
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"
    }
  ]
}

What events are 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

if you don't see an action you are interested in keeping an eye on, please let us know.

Coming soon: more events tracked