Events API

This section describes the REST APIs for operations within the OneWelcome Identity Platform.

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.

The API client requires the scope onegini_api_events (Events API).

Endpoints

Search for events

Endpoint: /oauth/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, an empty result set is returned.
size	no	20	Number of results within a 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…CCACB1C44F7434	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 Audit 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 Audit events 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.

Search filters are optional. When multiple filters are specified, all conditions must be met (for example, combined using the AND operator). event_type is the only exception where the system uses an OR operation so that you can filter on a specific set of events. The results are sorted descending by timestamp (most recent 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. Typically a user with administrative privileges.
occurred	Milliseconds elapsed from epoch since the event occurred.

Example search command:

GET /api/v1/events?event_type=ADMIN_CLIENT_DELETED&event_type=API_DEVICE_REMOVED&start_date=1555405987532 HTTP/1.1
Host: onewelcome.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": []
    }
}

Events API

Authentication

Endpoints

Search for events

On this page

Suggest A Change