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
  3. What are Audit Logs?
  4. Who is allowed to audit what?
  5. How to filter audit queries?
  6. How to retrieve Audit Logs in
  7. Why using Audit Logs on


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.

Audit logs

What are 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 audit-log/pryv-api. You can find its defails here.

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

Who is allowed to audit what?

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

Personal token

Whe using a personal token, you can query actions performed by any other access. You can also create app and shared accesses to audit any other access, by adding permissions to the audited access id, such as:

  "streamId": ":_audit:access-MY_AUDITED_ACCESS_ID",
  "level": "read"

App and shared tokens

When using an app or shared token, you can only query actions performed by the access you are using, and the permissions you were explicitely given on others.

How to filter audit queries?

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.

How to retrieve Audit Logs in

Build streamId

You can obtain the streamId related to the access you wish to audit by prefixing :_audit:access- to the access id such as:


Streams parameter

In order to obtain audit events, you must specify the audit stream(s) in the streams parameter of the events.get API method. You can fetch any audit log by providing :_audit: or a specific one by providing an access or method id.

Why using Audit Logs on

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

Why using Audit Logs