Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Events

Logs events API

search

Please Note:

Logs events API

The Active Search Event Store Reader API provides access to log event data stored in the Active Search database. The API allows you to query events, filter event data, and retrieve aggregated event information.

The API applies to only log events and does not apply to public events.

The API requires the active-search audience for all requests.

Event data is retained for 14 days. Events older than 14 days are automatically deleted from the system.

Authentication and authorization

The API uses OAuth2 authentication. You must include a valid access token in the Authorization header of your requests.

All requests require the active-search audience.

Machine-to-machine authentication

For machine-to-machine (M2M) integration, you must obtain an access token with the required OAuth2 scopes.

Required scopes:

Endpoint Required scope
/api/v1/query log-event-store:all-events:get
/api/v1/query-user-events log-event-store:user-events:get
/api/v1/aggregation log-event-store:all-events:get

Example M2M request:

curl -X POST https://your-domain/active-search-event-store/api/v1/query \
  -H "Authorization: Bearer <m2m-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 20
  }'

Admin user authentication

For admin user access, authentication requires both a valid access token and the log_events_read role.

Required role:

Endpoint Required role
/api/v1/query log_events_read
/api/v1/aggregation log_events_read

The /api/v1/query-user-events endpoint does not require the log_events_read role, but you must include a filter for actor.id in the request body.

Example admin user request:

curl -X POST https://your-domain/active-search-event-store/api/v1/query \
  -H "Authorization: Bearer <admin-user-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 20
  }'

To access the /api/v1/query and /api/v1/aggregation endpoints, admin users must have the log_events_read role assigned to their account.

API endpoints

Query all events

Retrieve events based on the specified filters.

Endpoint: POST /active-search-event-store/api/v1/query

M2M authentication: Requires the log-event-store:all-events:get scope

Admin user authentication: Requires the log_events_read role

Request body

The request body must contain a JSON object with the following optional fields:

Field Type Description
limit integer The maximum number of events to return must be between 1 and 100. Default is 50.
before string Return events that occurred before this timestamp. Format: ISO 8601 date-time with time zone.
after string Return events that occurred after this timestamp. Format: ISO 8601 date-time with time zone.
filters object Map of field names to filter conditions. See Filter conditions.

Example request

curl -X POST https://your-domain/active-search-event-store/api/v1/query \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 20,
    "after": "2024-01-01T00:00:00Z",
    "before": "2024-01-31T23:59:59Z",
    "filters": {
      "type": {
        "operator": "IS",
        "value": "AdminAuthenticationSuccessEvent"
      }
    }
  }'

Response structure

The endpoint returns a JSON object with two main sections: metadata and events.

Metadata fields:

Field Type Description
count integer The number of events returned in this response
hasMore boolean Indicates whether more events are available beyond this result set. Use this to determine if you need to make additional paginated requests.
oldest string The timestamp of the oldest event in the result set. Use this value in the before parameter to retrieve the next page of older events.
newest string The timestamp of the newest event in the result set

Events array:

The events array contains the matched event objects. Each event has the following structure:

Field Type Description
id string Unique identifier for the event
type string The event type, such as AdminAuthenticationSuccessEvent or TokenRequestAccessTokenCreatedEvent
description string Human-readable description of the event
producerId string Identifier of the service that produced this event
producerInstanceId string Unique identifier of the specific service instance that produced the event
subjects array Array of subjects affected by this event. Each subject has an id and type
occurredTime string Timestamp when the event occurred, in ISO 8601 format with time zone
tags array Array of tags associated with the event, such as EXPORTABLE or ERROR
userAgent string User agent string if the event was triggered by a browser or client application
hostIp string IP address associated with the event
traceId string Distributed tracing identifier for correlating events across services
subject object Primary subject of the event, containing id and type fields
actor object The entity that performed the action. Contains id and actorType fields.
actingApplication object The application that performed the action. Contains id and type fields.
payload string JSON string containing additional event-specific details

Example response

{
  "metadata": {
    "count": 3,
    "hasMore": true,
    "oldest": "2024-01-15T10:05:23.536479852Z",
    "newest": "2024-01-15T14:40:56.946916329Z"
  },
  "events": [
    {
      "id": "1c87995b-f8dc-4870-9aa9-0c3cdf3750a5",
      "type": "AdminAuthenticationSuccessEvent",
      "description": "User has successfully logged into the admin console.",
      "producerId": "access-admin",
      "producerInstanceId": "8ec3b74f-0c7c-4da0-b886-fdd141393821",
      "subjects": [],
      "occurredTime": "2024-01-15T13:40:46.358988434Z",
      "tags": ["EXPORTABLE"],
      "hostIp": "192.168.1.100",
      "actor": {
        "id": "a47e2f4e-3cf4-479c-b51c-6470f4f3c251",
        "actorType": "ADMIN_USER"
      },
      "payload": "{\"id\":\"cc062647-6e31-447f-8250-de71acae0623\",\"clientIp\":\"192.168.1.100\",\"eventDate\":1773150046348,\"details\":\"User Roles: ACCESS_USER_MANAGEMENT, ACCESS_WRITE, ACCESS_READ\",\"eventType\":\"ADMIN_AUTHENTICATION_SUCCESS\",\"adminUserId\":\"a47e2f4e-3cf4-479c-b51c-6470f4f3c251\"}"
    },
    {
      "id": "93abffa2-0b08-434d-9daf-ef84fd796770",
      "type": "TokenRequestAccessTokenCreatedEvent",
      "description": "Access token created via provided authorization code.",
      "producerId": "access",
      "producerInstanceId": "ebe7ec79-74ab-4f04-b92c-07312b8f0d9c",
      "subjects": [
        {
          "id": "AT.e8bb6d3b-24d9-45c1-988f-3e03a9afc911",
          "type": "Access token"
        }
      ],
      "occurredTime": "2024-01-15T13:26:57.911778874Z",
      "tags": ["EXPORTABLE"],
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "hostIp": "192.168.1.50",
      "traceId": "b619ae1f-1d5c-9d3b-854e-d810d4464e58",
      "subject": {
        "id": "AT.e8bb6d3b-24d9-45c1-988f-3e03a9afc911",
        "type": "Access token"
      },
      "actingApplication": {
        "id": "bde30d3a-9e09-4db5-b2d6-e3e17cdb6b05",
        "type": "WEB_CLIENT"
      },
      "payload": "{\"id\":\"3f029cb3-71ef-450c-9b47-1ade8151b11a\",\"clientIp\":\"192.168.1.50\",\"requestId\":\"b619ae1f-1d5c-9d3b-854e-d810d4464e58\",\"eventDate\":1773149217902,\"details\":\"Access token created via provided authorization code.\",\"eventType\":\"TOKEN_REQUEST_ACCESS_TOKEN_CREATED\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36\",\"clientId\":\"bde30d3a-9e09-4db5-b2d6-e3e17cdb6b05\"}"
    },
    {
      "id": "d127d947-f16e-4a07-80d9-bbcc975fbd00",
      "type": "EventExporterBlocked",
      "description": "Exporter is blocked due to too many errors.",
      "producerId": "event-exporting-service",
      "producerInstanceId": "ea0d0309-6051-4698-8669-36eee2d5f64a",
      "subjects": [
        {
          "id": "fce773ce-912b-45d8-a029-4d8f12e529a1",
          "type": "Event exporter"
        }
      ],
      "occurredTime": "2024-01-15T13:13:55.998508557Z",
      "tags": ["ERROR", "EXPORTABLE"],
      "subject": {
        "id": "fce773ce-912b-45d8-a029-4d8f12e529a1",
        "type": "Event exporter"
      },
      "payload": "{\"id\":\"fce773ce-912b-45d8-a029-4d8f12e529a1\",\"type\":\"HTTP\"}"
    }
  ]
}

Use the metadata.hasMore field to determine if you need to fetch additional pages. If hasMore is true, make another request with the before parameter set to the metadata.oldest value to retrieve older events.

Query user events

Retrieve events for a specific user. This endpoint is restricted to user-specific data and requires the user identifier in the request.

Endpoint: POST /active-search-event-store/api/v1/query-user-events

M2M authentication: Requires the log-event-store:user-events:get scope

Admin user authentication: Does not require a specific role

Required filter: You must include a filter for actor.id in the request body, to identify which user's events to retrieve.

Request body

The request body has the same structure as the query all events endpoint, but you must include a filter for actor.id.

Example request

curl -X POST https://your-domain/active-search-event-store/api/v1/query-user-events \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50,
    "filters": {
      "actor.id": {
        "operator": "IS",
        "value": "user123"
      },
      "type": {
        "operator": "IN",
        "values": ["AdminAuthenticationSuccessEvent", "TokenRequestAccessTokenCreatedEvent"]
      }
    }
  }'

Response

The endpoint returns a JSON object with the same structure as the query all events endpoint, containing metadata and events fields. See the query all events response structure for details.

Get aggregated events

Retrieves aggregated event field data from the Active Search database. This endpoint helps you discover available filter values by returning all unique values for filterable fields in the event store.

Use this endpoint to:

  • Discover available event types before filtering.
  • Find all producer IDs in the system.
  • Identify available application types and identity provider types.
  • Build dynamic filter dropdowns in your user interface.

Endpoint: GET /active-search-event-store/api/v1/aggregation

M2M authentication: Requires the log-event-store:all-events:get scope

Admin user authentication: Requires the log_events_read role

Example request

curl -X GET https://your-domain/active-search-event-store/api/v1/aggregation \
  -H "Authorization: Bearer <your-access-token>"

Example response

{
  "aggregates": {
    "actingApplication.id": [
      "console-ui",
      "access",
      "access-engine-client",
      "identity-store-s2s",
      "access-admin-s2s"
    ],
    "actingApplication.type": [
      "WEB_CLIENT",
      "API_CLIENT",
      "OAUTH"
    ],
    "subject.type": [
      "Access token",
      "POLICY",
      "IDENTITY",
      "Web client",
      "Scope"
    ],
    "producerId": [
      "access",
      "identity-store",
      "access-admin",
      "consent-management-service",
      "tenant-service"
    ],
    "type": [
      "TokenRequestAccessTokenCreatedEvent",
      "IDENTITY_UPDATED",
      "ATTRIBUTE_ADDED",
      "ATTRIBUTE_DELETED",
      "AdminAuthenticationSuccessEvent",
      "ApiScopeUpdatedEvent"
    ],
    "actor.identityProvider.type": [
      "OIDC",
      "SAML"
    ]
  }
}

The response contains a map of field names to arrays of unique values. You can use these values to construct filters for the query endpoints.

Filter conditions

Filters allow you to narrow down the events that the API returns. Each filter consists of a field name and a filter condition.

Filter structure

Each filter condition has the following structure:

Field Type Required Description
operator string Yes The comparison operator to use. See Operators
value string No The value to compare against. Required for IS, IS_NOT, CONTAINS, and DOES_NOT_CONTAIN operators.
values array of strings No Array of values for multi-value operators. Required for the IN and NOT_IN operators.

Operators

The following operators are available for filter conditions:

Operator Description Requires value Requires values
IS Field value equals the specified value Yes No
IS_NOT Field value does not equal the specified value Yes No
CONTAINS Field value contains the specified value Yes No
DOES_NOT_CONTAIN Field value does not contain the specified value Yes No
IS_EMPTY Field is empty or null No No
IS_NOT_EMPTY Field is not empty and not null No No
IN Field value matches one of the specified values No Yes
NOT_IN Field value does not match any of the specified values No Yes

Filter restrictions

The following restrictions apply to filters:

  1. You cannot filter on the payload field.

  2. The occurredTime field does not support the CONTAINS or DOES_NOT_CONTAIN operators.

  3. The hostIp field does not support the CONTAINS or DOES_NOT_CONTAIN operators.

  4. You can only filter once per field. If you need to match multiple values for the same field, use the IN operator instead of multiple IS filters.

Warning

Invalid filter combinations:

json { "filters": { "eventType": { "operator": "IS", "value": "USER_LOGIN" }, "eventType": { "operator": "IS", "value": "USER_LOGOUT" } } }

This will not work because you cannot filter on the same field twice. Use the IN operator instead:

json { "filters": { "eventType": { "operator": "IN", "values": ["USER_LOGIN", "USER_LOGOUT"] } } }

Filter examples

Filter by exact match

{
  "filters": {
    "eventType": {
      "operator": "IS",
      "value": "USER_LOGIN"
    }
  }
}

Filter by multiple values

{
  "filters": {
    "eventType": {
      "operator": "IN",
      "values": ["USER_LOGIN", "USER_LOGOUT", "PASSWORD_CHANGE"]
    }
  }
}

Filter by date range

{
  "after": "2024-01-01T00:00:00Z",
  "before": "2024-01-31T23:59:59Z",
  "filters": {
    "eventType": {
      "operator": "IS",
      "value": "USER_LOGIN"
    }
  }
}

Filter by field existence

{
  "filters": {
    "userId": {
      "operator": "IS_NOT_EMPTY"
    }
  }
}

Exclude specific values

{
  "filters": {
    "eventType": {
      "operator": "NOT_IN",
      "values": ["SYSTEM_HEARTBEAT", "HEALTH_CHECK"]
    }
  }
}

Combine multiple filters

{
  "limit": 100,
  "after": "2024-01-01T00:00:00Z",
  "filters": {
    "eventType": {
      "operator": "IS",
      "value": "USER_LOGIN"
    },
    "actor.id": {
      "operator": "IS_NOT_EMPTY"
    },
    "result": {
      "operator": "IS",
      "value": "SUCCESS"
    }
  }
}

Limitations

The Active Search Event Store API has the following limitations:

Limitation Value Description
Data retention 14 days Events are automatically deleted after 14 days. You cannot query events older than 14 days.
Maximum results 100 You can retrieve a maximum of 100 events per request. To retrieve more events, use pagination with before and after parameters.
Default results 50 If you do not specify a limit, the API returns 50 events by default.

Caution

To retrieve more than 100 events, you must make multiple requests using the before parameter to page through the results. Use the timestamp of the oldest event from the previous response as the before value in the next request.

Error responses

The API returns standard HTTP status codes to indicate success or failure.

Status code Description
200 The request was successful.
400 The request is invalid. Check the error message for details.
401 Authentication failed. Check your access token.
403 Authorization failed. You do not have the required scope or role.
500 An internal server error occurred. Contact support if the problem persists.

Complete example

The following example demonstrates how to query user login events for a specific user within a date range:

curl -X POST https://your-domain/active-search-event-store/api/v1/query-user-events \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 20,
    "after": "2024-03-01T00:00:00Z",
    "before": "2024-03-31T23:59:59Z",
    "filters": {
      "actor.id": {
        "operator": "IS",
        "value": "user123"
      },
      "type": {
        "operator": "IS",
        "value": "AdminAuthenticationSuccessEvent"
      }
    }
  }'

This request retrieves up to 20 authentication success events for user user123 that occurred in March 2024. The response will include the metadata object showing the count, whether more events are available, and the timestamp range of the returned events.

On this page