Audit Trail
  • 13 Nov 2023
  • 9 Minutes To Read
  • Dark
    Light
  • PDF

Audit Trail

  • Dark
    Light
  • PDF

Article Summary

Early Access Feature
The following feature may incur additional costs. If you would like to request early access to this feature, please get in touch with your Mambu Customer Success Manager or contact us through Mambu Support 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. 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.

We start storing events from the point that the audit trail feature is enabled. Events are stored for the same length of time as the one defined in your data agreement. For more information, please contact your Customer Success Manager.

Please be Aware

The audit trail feature only covers the Mambu application. Additionally, configuration as code payloads are not covered by the audit trail feature. We recommend using version control to retain a comprehensive changelog for these payloads.

Auditing for actions taken on add-on products, such as the Mambu Payment Gateway (MPG) or the Mambu Process Orchestrator (MPO), may be covered by their own logging and auditing solutions.

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 that has the Manage Audit Trail (MANAGE_AUDIT_TRAIL) permission assigned to it. For more information, see API Consumers.

Supported operations

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

ActionEndpointDescription
GET/v1/eventsGet 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.

NameDescriptionRequired
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.
fromAllows 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.
sizeThe 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_byThe 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_orderThe 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 fieldsDescriptionSupported operators
event_sourceThe events that are supposed to be audited fall within the following categories: API, UIeq, ne, in
request_uriThe part of the request's URL after the base URL and up to the query stringeq, ne, startsWith, in, contains
request_methodHTTP request method (GET, POST, PUT, etc)eq, ne, in
request_payloadThe 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_agentThe value of HTTP user agent headereq, ne, startsWith, in, contains
resourceFor API requests, this value is obtained from parsing the URL. e.g for /api/clients" the resulting value is "clients"eq, ne, startsWith, in, contains
resource_fragmentFor API requests this holds the request URI
For UI operations this holds the raw URL hash
eq, ne, startsWith, in, contains
usernameThe user who carried out the action or the name of the API consumer (may be empty)eq, ne, startsWith, in, contains
client_ipIP address from http request or X_FORWARDED_FOR header if presenteq, ne, startsWith, in
response_codeHTTP response codeeq, ne, in, gt, gte, lt, lte
occurred_atThe 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_payloadThe 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

OperatorDescriptionExample
eqEquals - exact match, applies to any type of fieldsusername[eq]=demo@mambu.com
neNot equals, applies to any type of fieldsusername[ne]=demo@mambu.com
gtGreater than, applies to numeric or date fieldsoccurred_at[gt]=2018-05-01
gteGreater than or equal, applies to numeric or date fieldsoccurred_at[gte]=2018-05-01
ltLess than, applies to numeric or date fieldsoccurred_at[lt]=2018-05-01
lteLess than or equal, applies to numeric or date fieldsoccurred_at[lte]=2018-05-01
startsWithStarts with, applies to string fieldsusername[startsWith]=demo
inElement in list (exact match), applies to any type of fieldsusername[in]=
user1@mambu.com,user2@mambu.com
containsThis 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.

Invalid characters in a header or path

When using basic authentication, the requests you make to any of our APIs must be RFC 7230 compliant. If you're using basic authentication and your request has an invalid character in either the header or the path, then you will receive a 400 Bad Request status code and this request will not be logged in audit trail. Invalid characters are any characters that are not included in ASCII.

We recommend validating your requests or using a well tested HTTP request library in your integrations. However if you experience any issues with repeated bad requests, please contact us through Mambu Support.

Example

The example below will result in a 400 Bad Request status code because one of the headers includes the á character which is not in the ASCII.

curl --location --request GET 'https://TENANT_NAME.mambu.com/api/clients' \
--header 'Accept: application/vnd.mambu.v2+json' \
--header 'Content-Type: application/json' \
--header 'á: value' \
--header 'Authorization: Basic {auth}' \
--data-raw ''

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,
IBAN

Was this article helpful?