How to download audit information from Clearance

Context

Clearance maintains extensive audit trails for users, cases and files. These records are available for download through endpoints provided in various services including:

• The Case Service API, which provides audit information for cases.
• The Document Service API, which provides audit information for evidence files.
• The User Manager Service API, which provides audit information for user activities.

🚧

Note

To use these endpoints, you must be a tenant administrator and have the "Access audit trail and create eDiscovery receipt" security policy.

The audit information is available from any of the services described above and is accessed through one of two possible API endpoints:

• The /history endpoint provides access to records associated with existing users, cases and files.
• The /suspiciousActivity endpoint is only available to the user manager and provides information about login attempts made by unknown users.

How to use the endpoints

To use these endpoints, you must page your download operation using the startingConcurrencyId field and the count field.

To download records from these endpoints:

1. Call the endpoint with an empty startingConcurrencyId and a count of 10 records.
2. Clearance will return a batch of 10 records. The 10th record will contain an initial value for startingConcurrencyId. This value must be provided in subsequent calls to the endpoint.
3. Call the endpoint a second time using the startingConcurrencyId from step 2 abode and a Count of 10.
4. Clearance will return the next 10 records in the sequence.
5. Continue updating the startingCondurrencyId and downloading until no more records are returned,

The history endpoint returns the records in a chronological order from newest to oldest.

The endpoints return a History model, for example:

{
  "Name": "[email protected]",
  "Entries": [
    {
      "Author": {
        "PrincipalId": 1234,
        "KId": "https://dems-prod-eus-keyvault.vault.azure.net:443/keys/company-user-1234",
        "Name": " ",
        "Username": "[email protected]"
      },
      "ConcurrencyId": "367f9d012febc9ffffc708b40a1473464324b898",
      "ParentReference": "dd1c7c852a853e9a99c5a72aad6a88d635891468",
      "TimestampUtc": "2023-02-21T21:31:56.5004092+00:00",
      "TreeReference": "eec4b78a811d9f704c684c07d6140322d69a305f",
      "IPAddress": "123.123.123.123",
      "Reason": {
        "Action": "Login",
        "Details": [
          "Login([email protected], B2B)"
        ]
      }
    },
    {
      "Author": {
        "PrincipalId": 1234,
        "KId": "https://dems-prod-eus-keyvault.vault.azure.net:443/keys/company-user-1234",
        "Name": " ",
        "Username": "[email protected]"
      },
      "ConcurrencyId": "77317fc21676083f59b29326ba4c45eff298962c",
      "ParentReference": "e1c57a24f571e0f0bbed4f06d592d7ee4963e252",
      "TimestampUtc": "2023-01-27T14:03:49.3605621+00:00",
      "TreeReference": "eec4b78a811d9f704c684c07d6140322d69a305f",
      "IPAddress": "123.123.123.123",
      "Reason": {
        "Action": "Logout",
        "Details": [
          "Logout([email protected])"
        ]
      }
    }
  ]
}