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

Name	Located in	Description	Mandatory	Schema
id	path	ID of the audit record for which you want to fetch the details	no	Array[string]

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

Audit endpoints in the REST API

Before you begin

GET /audit/api/v1/audit_records/{id}

Request URL

Request header

Parameters

Successful response

Unsuccessful response

PATCH /audit/api/v1/audit_policies

Request URL

Request header

Request body

Example request body

Parameter

Successful response

Unsuccessful response

POST /audit/api/v1/audit_records/search

Request URL

Request header

Request body

Example request body

Parameters

Columns supported for search

Successful response

Unsuccessful response

Comments

GET `/audit/api/v1/audit_records/{id}`

PATCH `/audit/api/v1/audit_policies`

POST `/audit/api/v1/audit_records/search`