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": "7"
}
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*