Events API

This section describes the REST APIs that delivers details about operations executed within the Onegini Token Server.

Authentication

All endpoints contained within the Events API are secured by API client credentials. To configure an API client, see the API Configuration topic guide.

It requires an API client with the scope onegini_api_events (Events API).

Endpoints

Search for events

  • Endpoint: /api/v1/events
  • Method: GET

Pagination specific request parameters:

Param Required Default value Description
page no 0 Specific result page. If the requested page is larger then the last available page, empty result set is returned.
size no 20 Number of the results within single page. The maximum page size is 1000.

Search criteria request parameters:

Param Example value Search criteria
user_id b3948273-117b-413a-9f8f-7e7750bbecc8 Return events specific to a given user. The same user may be interacting via different clients. This criteria is case insensitive.
client_id 873BE193F83821A32DA4​1FDB6712ABCE89DF105E​9C874A7452CCACB1C44F​7434​ Return events specific to a given client. This could be either a web client or a specific mobile client.
event_type ADMIN_​CLIENT_​DELETED Return events of a specific type. See appendix for a complete list of events. Event type needs to be given in uppercase and with a underscore (_) as a separator. Multiple parameters are allowed.
exclude_event_type AUTHZ_​REQUEST_​GRANT_​CREATED Return events of a specific type. See appendix for a complete list of events. Event type needs to be given in uppercase and with a underscore (_) as a separator. Multiple parameters are allowed.
transaction_id ONEGINI_95830280-7ade-4527-95ce-67db29dc33d5 Return events related to a specific transaction.
start_date 1555405987532 Return events which occurred at or after a specific point in time.
end_date 1555405989532 Return events which occurred before or at a specific point in time.
end_date_exclusive true Exclude from the results the events that occurred exactly at a point in time specified by end_date timestamp.

All search criteria filters are optional, when multiple filters are specified all conditions need to be met (ie. conditions are combined using AND operator). event_type is the only exception where it will use an OR so you can filter on a specific set of events. The results are sorted descending by a timestamp (latest first).

JSON Attributes:

Attribute Description
event_identifier UUID identifying the event
event_name Display friendly name of the event type
event_type Raw value of the event type
client_id Client identifier associated with the event
app_name Name of the mobile app or web client associated with the event
transaction_id Transaction identifier associated with the event
user_id User identifier associated with the event
client_ip Ip address of the device associated with the event
user_agent User agent of the device associated with the event
event_agent_user User identifier of agent who performed the action. This usually represents a user with administrative privileges
occurred Milliseconds elapsed from epoch since the event occurred
GET /api/v1/events?event_type=ADMIN_CLIENT_DELETED&event_type=API_DEVICE_REMOVED&start_date=1555405987532 HTTP/1.1
Host: onegini.example.com

Example success response:

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
    "result_set": [
        {
            "event_identifier": "0b2463c1-5808-482f-ab20-b9971924cb5a",
            "event_name": "Admin client deleted",
            "event_type": "ADMIN_CLIENT_DELETED",
            "client_id": "873BE193F83821A32DA41FDB6712ABCE89DF105E9C874A7452CCACB1C44F7434",
            "app_name": "Example app",
            "transaction_id": "ONEGINI_95830280-7ade-4527-95ce-67db29dc33d5"
            "user_id": "b3948273-117b-413a-9f8f-7e7750bbecc8",
            "client_ip": "192.168.0.1",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36",
            "event_agent_user": "admin",
            "occurred": 1555405987532
        },
        {
            ... more search results
        }
    ],
    "pagination": {
        "total_results": 3,
        "offset": 0,
        "page_size": 10,
        "max_visible": 5,
        "pages_before": 2,
        "range_start": 1,
        "range_end": 3,
        "first_page": true,
        "last_page": true,
        "number_of_pages": 1,
        "previous_page": null,
        "next_page": null,
        "visible_pages": []
    }
}