Audit endpoints in the REST API

The following section provides a list of supported endpoints for auditing and details about running these endpoints. For information about auditing concepts, see Viewing-audit-records-in-BMC-Helix-Dashboards. 

Before you begin

Before you run an endpoint, you must authenticate yourself. For more information, see Access-and-authentication-for-the-REST-API.

GET /audit/api/v1/audit_records/{id}
Get details of an audit record

You need read permissions to be able to run this API endpoint.

Request URL
https://<BMC Helix Portal URL>/audit/api/v1/audit_records/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
 "audit_id": "a84d4960-ce68-407e-9d64-dc6b57a0e98b",
 "audit_category": "CONFIg",
 "app_id": "IMS",
 "object_id": "10909023123213",
 "object_name": "role1",
 "object_type": "ROLE",
 "object_category": "RBAC",
 "object_details": "ROLE_ADD_USER",
 "operation_type": "POST",
 "operation_sub_type": "ADD",
 "operation_status": "SUCCESS",
 "description": "Adding a role to user",
 "activity_time": "2021-01-03T10:42:51.624",
 "transaction_id": "1123213123123",
 "change_values": {
   "previous_value": {
     "val": "No Role"
   },
   "new_value": {
     "val": "New Role Added"
   }
 },
 "login_id": "vegauser",
 "user_id": "237247339985698"
}
Unsuccessful response
{
 "timestamp": "2022-01-04T11:28:13.700100Z",
 "code": 403,
 "message": "FORBIDDEN:Operation is not allowed."
}
patch /audit/api/v1/audit_policies
Update retention period of an audit record
Request URL
https://<BMC Helix Portal URL>/audit/api/v1/audit_policies
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
  "retention_time": "string"
}
Example request body
{
  "retention_time": "10"
}
Parameter

Name

Located in

Description

Mandatory

Schema

retention_time

body

Number of days for retaining the audit record.

yes

integer

Successful response
{
    "message": "SUCCESS"
}
Unsuccessful response

Scenario 1: Trying to set negative value "-7" for retention time

{
    "timestamp": "2022-01-24T12:38:59.932900Z",
    "code": 2300,
    "message": "BAD_REQUEST",
    "error": "Invalid value of update policies entered."
}

Scenario 2: Trying to set string value "Seven" for retention time

{
    "timestamp": "2022-01-24T12:38:59.932900Z",
    "code": 2300,
    "message": "BAD_REQUEST",
    "error": "Invalid value of update policies entered."
}
POST /audit/api/v1/audit_records/search
Search an audit record
Request URL
https://<BMC Helix Portal URL>/audit/api/v1/audit_records/search
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
  "select_string": "string",
  "search_string": "string",
  "activity_from_date_time": "string",
  "activity_to_date_time": "string",
  "page_index": 0,
  "page_size": 0
}
Example request body
{
  "select_string": "appId",
  "search_string": "appId='IMS'",
  "activity_from_date_time": "2010-08-16 10:42:51",
  "activity_to_date_time": "2022-02-21 10:42:51",
  "page_index": 0,
  "page_size": 100
}
Parameters

Name

Located in

Description

Mandatory

Schema

select_string

body

Specific column of an audit record.

no

string

search_string

body

Search value in audit record.

no

string

activity_from_date_time

body

Display of all suitable audit records starting from this time.


yes

timestamp

activity_to_date_time

body

Display of all suitable audit records up to this time.

yes

timestamp

page_index

body

Page index

no

integer

page_size

body

Page size

no

integer

Columns supported for search

auditId

auditCategory
appId
objectName
objectType
objectCategory
objectDetails
operationType
operationSubType
operationStatus='SUCCESS'
activityTime
source
loginId

Successful response
{
    "metadata": {
        "page_index": 0,
        "page_size": 100,
        "total_records": 1
    },
    "data": [
        {
"auditId": "277ee0e7-4c37-415d-bc8d-20d831fd5ece",            
"appId": "IMS"
        }
    ]
}
Unsuccessful response

Scenario 1: Searching audit record in incorrect format

{
    "timestamp": "2022-02-21T14:13:21.154141Z",
    "code": 2300,
    "message": "BAD_REQUEST",
    "error": "Invalid token in search_string: appId=IMS"
}

Scenario 2: Searching audit record with missing activity time and date value

{
    "timestamp": "2022-02-21T14:15:04.007938Z",
    "code": 400,
    "message": "BAD_REQUEST",
    "error": "activity_to_date_time can not be empty/null, please enter date in yyyy-MM-dd HH:mm:ss format"
}

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*