Audit Trail
  • 21 Feb 2022
  • 8 Minutes To Read
  • Dark
    Light
  • PDF

Audit Trail

  • Dark
    Light
  • PDF

Early Access Feature
If you would like to request early access to this feature, please get in touch with your Mambu Customer Success Manager to discuss your requirements. For more information, see Mambu Release Cycle - Feature Release Status.

The audit trail capability tracks all activities that have been performed in the Mambu Core Banking system via the UI or API v1 and v2. Audit records are grouped per tenant. Events are stored indefinitely from the point that audit trail is enabled. You can search and filter through stored events using a simple API or periodically pull batches of events into your own log management software for further analysis.

Please be Aware

There are some actions and pieces of data that are not tracked, including:

  • Actions taken on certain add-on products, such as the Mambu Payment Gateway (MPG) or Mambu Process Orchestrator (MPO). These products may provide their own logging and auditing solutions.
  • Configuration as code payloads. We recommend using version control for these in order to retain a comprehensive changelog.
  • Viewing the audit trail itself.

With audit trail you are able to:

  • Identify what Mambu application users have done and when they did it.
  • Choose who to audit and what type of information to audit.

Some example use cases might be:

  • Investigate suspicious activity or potential fraud.
  • Detect actions performed by an unauthorized user.
  • Monitor and gather data about specific activities.
  • Generate compliance and audit reports from audit data.
Please Be Aware

Use of Audit Trail requires API Consumers, which is an Early Access feature. For more information, see Authentication below.

Authentication

To authenticate audit trail requests you must use an API key generated by an API consumer of the type 'audit trail'. For more information on the API consumers feature, see API Consumers.

For information on how to set up your API key for audit trail in the Mambu UI, see Creating API consumers.

Supported operations

Base URL: https://TENANT_NAME.mambu.com/api

Action Endpoint Description
GET /v1/events Get a list of events.

Headers

Other than the authentication header with the API key, there are no other additional headers required.

Parameters

The following is a list of query parameters you can use to filter your requests.

Name Description Required
FIELD_NAME[OPERATOR]
=FIELD_VALUE
A filter using a LHS bracket with an operator. There can be more than one filter used per request. For a list of field names, see Field Names below. For a list of available operators, see Operators below.
from Allows you to offset results, the default is 0. Can be used in conjunction with the size parameter to return equally sized sets. Note that the number provided is not inclusive, so, for example, given a total results set of 100 events, from=10 will return the 11th to the 100th event. For information about limits, see Warnings below.
size The number of event entries to return. If not specified, the default is 100. Can be used with the from parameter to page through a list of events in equally sized sets. For information on limits, see Warnings below.
sort_by The field name by which to sort the returned events. For a list of field names, see Field Names below. If not specified the results will be sorted chronologically using the ocurred_at field.
sort_order The order by which to sort the returned events using either asc (ascending) or desc (descending) order. If not specified, the default is descending order.

Requests

The following section shows sample requests using curl. For all examples, replace TENANT_NAME with your actual tenant URL.

Sample request

Get all UI login activities for today

curl --location -g --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?event_source[eq]=UI&resource[contains]=login&occurred_at[gte]=2021-08-08T00:00:00.000Z' \
--header 'apikey: {apikey}'

{apikey} is an API key from the audit trail API consumer. For more information about authentication, see Authentication above.

Sample response

{
    "events": [
        {
            "occurred_at": "2021-08-09T09:47:04.664Z",
            "response_code": 200.0,
            "resource": "login",
            "event_source": "UI",
            "client_ip": "80.131.123.137",
            "request_method": "POST",
            "request_payload": "{\"username\":[\"johnsmith\"],\"loginType\":[\"onlineLogin\"]}",
            "resource_fragment": "/servlet/login",
            "request_uri": "/servlet/login",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.4515.131 Safari/537.36",
            "response_payload": "SUCCESS",
            "username": "johnsmith"
        }
    ],
    "from": 0,
    "size": 100,
    "totalItemsCount": 1
}

Additional sample requests

{apikey} is an API key from the audit trail API consumer. For more information about authentication, see Authentication above.

Get API requests with failed authorization

curl --location -g --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?event_source[eq]=API&response_code[eq]=401&=' \
--header 'apikey: {apikey}'

Get the last ten clients viewed by user “johnsmith”

curl --location -g --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?event_source[eq]=UI&occurred_at[gte]=2020-04-09T19:20:01.040Z&resource[eq]=client&username[eq]=johnsmith&request_uri[eq]=/desktop/dispatch/GetClient&size=10' \
--header 'apikey: {apikey}'

Page through all events in batches of 10

  1. curl --location --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?from=0&size=10&occurred_at[gte]=2021-08-11T11:00:00.000Z' \
    --header 'apikey: {apikey}'
    
  2. curl --location --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?from=10&size=10&occurred_at[gte]=2021-08-11T11:00:00.000Z' \
    --header 'apikey: {apikey}'
    
  3. curl --location --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?from=20&size=10&occurred_at[gte]=2021-08-11T11:00:00.000Z' \
    --header 'apikey: {apikey}'
    

Notice that in this last example we are using a filter on the occurred_at field. This is important as, if no constraints are used and the default descending chronological order is applied, any new events matching your query will be included in the index and possibly cause your sets to intersect. Fixing the time at a given point is one way to ensure new events are not included in your results and your sets contain only unique events.

Parameter components

Field Names

Event fields Description Supported operators
event_source The events that are supposed to be audited fall within the following categories: API, UI eq, ne, in
request_uri The part of the request's URL after the base URL and up to the query string eq, ne, startsWith, in, contains
request_method HTTP request method (GET, POST, PUT, etc) eq, ne, in
request_payload The raw request data as a string, with sensitive information removed (see details in note below). Parameter may be empty. eq, ne, startsWith, in, contains
user_agent The value of HTTP user agent header eq, ne, startsWith, in, contains
resource For API requests, this value is obtained from parsing the URL. e.g for /api/clients" the resulting value is "clients"
For UI operations this is obtained from parsing the URL hash. e.g for "#admin.tab=admin_reports.report_type=CLIENT" the resulting value is "admin_reports"
eq, ne, startsWith, in, contains
resource_fragment For API requests this holds the request URI
For UI operations this holds the raw URL hash
eq, ne, startsWith, in, contains
username The user who carried out the action or the name of the API consumer (may be empty) eq, ne, startsWith, in, contains
client_ip IP address from http request or X_FORWARDED_FOR header if present eq, ne, startsWith, in
response_code HTTP response code eq, ne, in, gt, gte, lt, lte
occurred_at The timestamp, in UTC, when the event has been generated (when creating queries on this field the provided values must be in ISO8601 standard) eq, ne, in, gt, gte, lt, lte
response_payload The raw response payload with sensitive information removed (see details in note below). A response payload is not included with every record. eq, ne, startsWith, in, contains

Operators

Operator Description Example
eq Equals - exact match, applies to any type of fields username[eq]=demo@mambu.com
ne Not equals, applies to any type of fields username[ne]=demo@mambu.com
gt Greater than, applies to numeric or date fields occurred_at[gt]=2018-05-01
gte Greater than or equal, applies to numeric or date fields occurred_at[gte]=2018-05-01
lt Less than, applies to numeric or date fields occurred_at[lt]=2018-05-01
lte Less than or equal, applies to numeric or date fields occurred_at[lte]=2018-05-01
startsWith Starts with, applies to string fields username[startsWith]=demo
in Element in list (exact match), applies to any type of fields username[in]=
user1@mambu.com,user2@mambu.com
contains This operator can be used with various content types. "key":"value" represents a search element. The order of the key and the value matters, for example, using the element "mykey": "myvalue" is not the same as "myvalue":"mykey". The operator works with multiple elements that are delimited by ',' .The order of the elements doesn’t matter, for example request_payload[contains]=
"key1":"value1","key2":"value2"will return the same results as request_payload[contains]=
"key2":"value2","key1":"value1".
request_payload[contains]=
"provisionedThroughFederation":
true, "detailsLevel":"BASIC"

Warnings

Data retrieval limits

Given a set of filter query parameters, you can only retrieve 10,000 entries.

The combination of the values of the size parameter and the from parameter must not exceed 10,000 or else you'll receive a 400 Bad Request status code with an error message such as:

"message": "From (10) and size (10000) combination exceed 10000, the maximum allowed window. Default size is 100"

The maximum value of the size parameter is 10,000. The maximum value of the from parameter is 10,000.

If you want to retrieve entries that are past the last 10,000 entries retrieved then you must use the filter query parameters to alter your request.

For example you can use the occurred_at parameter and pass in an operator in order to narrow your query.

Example

In the following example we show how you can use the filter parameters to change your requests and retrieve different sets of events.

Suppose that you want to get a simple list of all the latest events that have happened in your tenant.

With the following request you would retrieve the 10,000 latest entries:

curl --location --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?size=10000' \
--header 'apikey: {apikey}'

Suppose the events retrieved are from the 4 August, 2021 until the 18 August, 2021.

If you wanted to retrieve events before the 4th August, 2021 then you could change your request by using the occurred_at filter query parameter and passing in an operator. For example:

curl --location -g --request GET 'https://TENANT_NAME.mambu.com/api/v1/events?size=10000&occurred_at[lte]=2021-08-04T00:00:00.000Z' \
--header 'apikey: {apikey}'

This could, for example, retrieve events from the 4 August, 2021 until the 13 July, 2021.

User-Agent header

When audit trail is enabled, you must provide a User-Agent header for all requests to any endpoint, or the request will fail with the error message:

{
    "returnCode": 4,
    "returnStatus": "INVALID_PARAMETERS",
    "errorSource": "The user agent cannot be null when the Audit Trail feature is enabled"
}

Note that if you are using a REST client like Postman or Curl, this header is probably provided automatically. However, if you generate a request to the API, you must provide it yourself.

The User-Agent header provides information regarding the browser and operating system (such as the browser version), and information about the library or tool issuing the request (such as the client Java version). It is generally used to assist with debugging problems.

Security

The following information is removed from request payloads when using audit trail:

PASSWORD,
PAGINATION_DETAILS,
FETCHING_INFO,
MOBILE_PHONE,
EMAIL_ADDRESS,
ADDRESSES,
BIRTH_DATE,
MOBILE_PHONE1,
MOBILE_PHONE2,
FIRST_NAME,
LAST_NAME,
HOME_PHONE,
MIDDLE_NAME,
NOTES,
GROUP_NAME,
ADDRESS_LINE_1,
ADDRESS_LINE_2,
ADDRESS_LATITUDE,
ADDRESS_LONGITUDE,
DESCRIPTION,
TITLE,
TEXT,
ASSET_NAME,
LOAN_NAME,
NAME,
POST_CODE,
COUNTRY,
REGION,
GENDER

Was This Article Helpful?

What's Next