Read events

The Event API provides a /get endpoint for retrieving events from 10Duke Enterprise in JSON format.

You can read events from different “feeds” as follows:

  • Read events from the feed of a specified event source. For example, your different deployments (production and non-production) are typically separate event sources for the event data written by 10Duke Enterprise.

  • Read events based on a specified event object type and ID. For the event data written by 10Duke Enterprise, this allows reading events based on the user ID associated with a specific authenticated user (the object type is user).

You can also use the command line tool provided by 10Duke. The tool reads events through the Event API in chunks, which is the recommended way.

Requests

The HTTP request format when reading events from a specified event source:

https://<event data service URL>/get/<event source ID>

Provide the URL of the event data service in your 10Duke Enterprise environment, and the ID of the event source from which you want to read events.

The HTTP request format when reading events for a specified event object type and ID (a specific user):

https://<event data service URL>/get/<eventObjectType>/<eventObjectId>

See information on the query parameters in the API reference.

Example requests

An example request to read a maximum of 100 events from a given event source (line breaks added for display purposes):

https://events.customer.10duke.net/get/customer-production-idp
   ?maxEventCount=100

And to further limit the request to events written after a specified time:

https://events.customer.10duke.net/get/customer-production-idp
   ?after=1584458420324003300
   &maxEventCount=100

Authorize requests

To authorize a request to read event data, create a JWT token.

In the JWT payload:

  • Include a claim with the identifier of the feed you’re reading events from (usually the event source), and set the value to true. You can also use an asterisk * to read from all feeds.

  • Set a value for the exp (expires) claim, and optionally for the iat (issued at) claim.

Example payload:

{
   "customer-production-idp": true,
   "iat": 1679392800,
   "exp": 1679396400
}

In the JWT header, set alg to RS256, RS384, or RS512. The algorithm to use depends on the length of the RSA keys used for authorization.

{
   "alg": "RS256"
}

Now sign the JWT token with the private key of the client reading the data. You get something like this:

eyJhbGciOiJSUzI1NiJ9.eyJteS10ZXN0Ijp0cnVlLCJpYXQiOjk0NjY4NDgwMCwiZXhwIjo5NDY2ODg0MDB9.jZQf4fQl0K...

When you send the GET request, include a Bearer token authorization header that specifies the signed token.

Example:

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJteS10ZXN0Ijp0cnVlLCJpYXQiOjk0NjY4NDgwMCwiZXhwIjo5NDY2ODg0MDB9.jZQf4fQl0K...

Responses

The response payload is the event data.

Example response:

[{
   "eventSourceId": "idp",
   "eventId": "74704f54-95b4-4666-8978-32cb31243f87",
   "data": {
      "remember": false,
      "requestId": "14b73930-2566-44bd-92ce-7e2253365001",
      "eventTime": 1679986446416,
      "authenticatedId": "de79770f-7818-4ede-b51d-d20759f43cda",
      "userId": "cba64356-9311-4e01-a865-63d468b37ae2",
      "authentications": ["password", "emailVerification", "acceptAgreements"]
   },
   "eventReceived_str": "1679986446432004247",
   "eventType": "UserAuthenticated",
   "version": "1.2.0",
   "eventReceived": 1679986446432004247,
   "expiresAt": 1687762446
},
{
   "eventSourceId": "idp",
   "eventId": "570be129-9915-4c38-a4d8-4680d3c663f5",
   "data": {
      "clientIpAddress": "1.2.3.4",
      "duration": 18,
      "method": "POST",
      "requestId": "14b73930-2566-44bd-92ce-7e2253365001",
      "eventTime": 1679986446400,
      "userAgent": "Example Client App 1.2.3",
      "url": "https://login.example.com/user/api/1/sessions/authentications",
      "status": 200
   },
   "eventReceived_str": "1679986446432018499",
   "eventType": "RequestProcessed",
   "version": "1.2.0",
   "eventReceived": 1679986446432018499,
   "expiresAt": 1687762446
}]

If no events are found, 10Duke Enterprise returns an empty response. If the request has errors, a response with HTTP status code 400 is returned.

See more information in the API reference.

Command line tool for reading events

10Duke provides a command line tool for reading events through the Event API in chunks.

You can, for example, manually run the tool and import the event data to a reporting tool, or you can schedule it to run and import the data to another system at specified intervals.

The command line tool requires that Node.js 12.16.1 or newer is installed.

Install the tool

You can find the tool in the 10Duke GitHub repository.

You can install the command line tool from the NPM repository:

$ npm i -g @10duke/event-data-reader-cli

Some environments may require that the installation is done with administrator permissions.

Test that the installation works by displaying the help:

$ event-data-reader -h

Run the tool

An example of how to use the tool to read events (line breaks added for display purposes):

$ event-data-reader {event data service URL}/get {event source}
   -k event.private.pem
   -a 2020-02-01
   -b 2020-03-01
   -o events.json

  • -k event.private.pem specifies the file that contains the private key required for authorizing event read operations.

  • -a 2020-02-01 and -b 2020-03-01 specify the timeframe from which events are read.

  • -o events.json requests the events to be returned in a JSON file events.json.

On this page