Audit Trail API

Margo Rey
  • Updated

    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:

    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"
    }
  ]
}

    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

    Related articles

    Table of contents