Skip to Content

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. 

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

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": [
        {
            "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*

BMC Helix Portal 22.3