Audit logs

In this guide we address developers that wish to use audit logs on to capture changes to a system and keep records of the interactions that were made with the data.
It describes what Audit Logs are, why to use them and how they were designed on It goes through a possible use case to explain how auditing works with

Table of content

  1. Introduction
  2. Audit Logs
    1. What are Audit Logs?
    2. Why using Audit Logs?
    3. How are logs organized in
    4. Retrieving Audit Logs in
  3. Use case: Keeping track of an API call
  4. Hands-on example
  5. Special features
    1. API endpoints
    2. Query parameters
    3. Search interface
    4. API results
    5. Configuration
  6. Conclusion


In regards to new requirements on data privacy, you need to be able by now to track all activities related to the personal data you hold on your servers. This includes tracking of consents, data accesses, data retrievals, but also tracking of data changes.

Audit logs are considered to be the best way of demonstrating compliance – and “demonstrating compliance” is a key point of new privacy regulations. Keeping logs of processes made on personal data is not only a best practice, but a must for you to achieve compliance.

Audit capabilities on now enable you to keep track of data in your system and to generate audit logs.


Let’s take a quick overview of what exactly are Audit logs.

An audit log shows “who” did “what” activity and “how” the system behaved. It comes in the form of a document that records chronologically all the interactions that were made with the personal data stored on the servers : what resources were accessed, the destination and source addresses, a timestamp and the user login information.

When using, it enables you to keep track of details about the actions performed by clients against accounts through the API.

You can take a look on what an Audit log looks like on :

  "id": ":_audit:ckqujnth400081eow07wcbfr7",
  "streamIds": [
  "time": 1625726631.928,
  "type": "audit-log/pryv-api",
  "content": {
    "source": {
      "name": "http",
      "ip": ""
    "action": "events.get",
    "query": {
      "toTime": "9900000000",
      "fromTime": "0",
      "limit": "100",
      "sortAscending": "false",
      "state": "all"
  "created": 1625726631.928,
  "createdBy": "system",
  "modified": 1625726631.928,
  "modifiedBy": "system",

As you may have recognized, it is an event of type log/user-api. You can find its defails here.

Audit logs are available through the Events API. However they are read only, thus cannot be modified.


You can filter the sort of logs you wish to query by action and access id. Each audit log gets 2 streamIds in the form of:

  1. :_audit:action-{method-id}, see API method ids.
  2. :_audit:access-{access-id}, the id of the access that performed the action.


The logs you are allowed to query depend on the access you are using.

Whe using a personal token, you can query actions performed by any other access.

When using an app or shared token, you can only query actions performed by the access you are using.


For information regarding the setup of

Why using Audit Logs on

Text to keep or replace by the drawing

In addition to providing proof of compliance and operational integrity, audit logs can help you monitor activity on your servers :

Why using Audit Logs

How to filter what to log

How are logs organized in ?

Retrieving Audit Logs in

Importantly, the logs on can only be fetched by presenting an authorization token, allowing to audit the actions that involved a given token.

Use case: Keeping track of an API call

Go through Emma use case.

Use case

Hands-on example

Explain the use case with API calls description.

Special features

API endpoints

Query parameters

Search interface

API results



If you wish to get more information on the data structure of an Audit Log in, please refer to the corresponding section of the API reference. It describes the main features of the data structure, while the methods relative to audit logs can be found in the API methods section.