Audit API

Note

API Version: 1.0.0
Base URL: https://next.itrslab.com/audit/api

The Audit API provides functionality to publish and query audit events within the ITRS system. This API allows you to track user actions, system events, and other auditable activities across your infrastructure.

Audit API endpoints Copied

Audit Events Copied

Publish an Audit Event Copied

POST /v1/audit-events

Publishes a new audit event to the system.

Parameters

Request Body

{
  "auditEvent": {
    "user": "string",
    "sourceDimensions": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "targetDimensions": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "outcome": "success",
    "action": "login",
    "timestamp": "2023-11-15T10:30:00Z",
    "context": {
      "sessionId": "sess_123456",
      "userAgent": "Mozilla/5.0"
    },
    "eventReporter": {
      "namespace": "authentication",
      "name": "login-service"
    }
  }
}

Response

Status Code: 200 OK

{}

Query Audit Events Copied

POST /v1/audit-events/query

Queries audit events based on specified criteria including time range, filters, and search terms.

Parameters

Request Body

{
  "from": "2023-11-15T00:00:00Z",
  "to": "2023-11-15T23:59:59Z",
  "filter": {
    "filteredFieldTerms": [
      {
        "stringFieldFilter": {
          "filteredField": {},
          "filterTerms": [
            {
              "filterValue": "login",
              "matchType": "MATCH_TYPE_EXACT"
            }
          ]
        }
      }
    ]
  },
  "globalSearchTerm": "john.doe",
  "pageSize": 50
}

Response

Status Code: 200 OK

{
  "auditEvents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "auditEvent": {
        "user": "john.doe@example.com",
        "sourceDimensions": [
          {
            "key": "hostname",
            "value": "workstation-01"
          }
        ],
        "targetDimensions": [
          {
            "key": "application",
            "value": "user-management-system"
          }
        ],
        "outcome": "success",
        "action": "login",
        "timestamp": "2023-11-15T10:30:00Z",
        "context": {
          "sessionId": "sess_123456",
          "userAgent": "Mozilla/5.0"
        },
        "eventReporter": {
          "namespace": "authentication",
          "name": "login-service"
        }
      }
    }
  ],
  "pagingToken": "eyJvZmZzZXQiOjUwfQ=="
}

Schemas Copied

AuditDataField Copied

Fields of the audit event data, used for the application of filters and retrieval of values for a specific field.

Type: object

Properties: None (empty object)

AuditEvent Copied

Representation of an audit event.

Type: object

Properties:

AuditEventFilter Copied

An audit event filter contains 1+ filter terms where each term may target any of the audit data fields. All filter terms are logically ANDed together.

Type: object

Properties:

AuditEventFilter_FilteredFieldTerm Copied

Each instance of this message describes a filter expression for a single data field. Within each field’s filter expression, there may be multiple filter terms on that field. Support for that, as well as determining how multiple terms are combined, is defined by the type of filter expression used for that field.

Type: object

Properties:

ContextFilterExpression Copied

Defines a filter on context map data in audit events. The terms within this filter expression are logically ORed together, thus enabling filtering based on multiple context key, value, or key/value data.

Type: object

Properties:

ContextFilterExpression_ContextFilterTerm Copied

Defines a filter term on the audit event data’s ‘context’ field to restrict query results to events matching this context filter term. An instance of this MUST define either a ‘keyFilter’, a ‘valueFilter’, or both. If both are provided, both must be true for context to match. To create a more complex filter, multiple filter terms may be defined for an expression, then each of the terms is ORed together.

Type: object

Properties:

Enum Values for Match Types:

• MATCH_TYPE_UNDEFINED
• MATCH_TYPE_EXACT
• MATCH_TYPE_CONTAINS
• MATCH_TYPE_STARTS_WITH

Dimension Copied

A single Entity dimension.

Type: object

Properties:

DimensionValueFilterExpression Copied

Defines a filter expression by combining 1+ filter terms. The dimensions to which the filter expression applies (source or target) is defined by the message in which this filter expression is defined. The terms are ANDed together.

Type: object

Properties:

Enum Values for Dimension Match Types:

• DIMENSION_MATCH_TYPE_UNDEFINED
• DIMENSION_MATCH_TYPE_EXACT_UNORDERED
• DIMENSION_MATCH_TYPE_STARTS_WITH_ORDERED
• DIMENSION_MATCH_TYPE_CONTAINS_UNORDERED

DimensionValueFilterExpression_DimensionValueFilterTerm Copied

Defines a filter term on dimension key/value data to restrict query results.

Type: object

Properties:

GetAuditEventsResponsePage Copied

List of audit events that satisfy the request.

Type: object

Properties:

NamespacedName Copied

A namespaced name identifier.

Type: object

Properties:

PublishAuditEventRequest Copied

Request to publish an audit event.

Type: object

Properties:

PublishAuditEventResponse Copied

Empty response to the request to publish an audit event.

Type: object

Properties: None (empty object)

QueryAuditEventsRequest Copied

Request to query audit events with filtering and pagination options.

Type: object

Properties:

ReturnedAuditEvent Copied

An audit event returned in query results.

Type: object

Properties:

StringFieldFilterExpression Copied

Defines a collection of filter terms on an ‘AuditEvent’s string field (i.e. ‘reporter_name’, ‘reporter_namespace’, ‘user’, ‘action’, or ‘outcome’) to restrict query results to events matching the condition created by logically ORing each of the terms together.

Type: object

Properties:

StringFieldFilterExpression_StringFieldFilterTerm Copied

Defines a filter term on an ‘AuditEvent’s string field (i.e. ‘reporter_name’, ‘reporter_namespace’, ‘user’, ‘action’, or ‘outcome’) to restrict query results to events matching this string field filter term.

Type: object

Properties:

Enum Values:

• MATCH_TYPE_UNDEFINED
• MATCH_TYPE_EXACT
• MATCH_TYPE_CONTAINS
• MATCH_TYPE_STARTS_WITH

Error Handling Copied

The API returns standard HTTP status codes:

• 200 OK - Request successful
• 400 Bad Request - Invalid request parameters or malformed request body
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Error responses include additional details in the response body when applicable.