Calling the Audit Logs API

This topic describes calling the Audit Logs API in Pigment. Use this API to help you programmatically monitor user activity, potential security issues, and suspicious behavior within your enterprise. You can use it in conjunction with a Security Information and Event Management (SIEM) or another auditing tool for active monitoring and tracking. 

Before you begin

Prerequisite information

• Workspace Account Type. Only Pigment members with the Account type Security Admin can create the Audit Logs API key you need to perform this task. For more information on API keys in Pigment, see Create an Audit Logs API Key.
• Bearer header. You must include your Audit Log API key in the bearer header of your API request. This assures secure authentication and authorization when you call the API.

Prerequisite tasks

We recommend that you obtain your Audit Logs API key before you start. For more information on Audit Logs API keys in Pigment, see Create an Audit Logs API Key. 

You should also read this article that gives an overview of the Audit Logs API: Monitor your Pigment Workspace with Audit Logs API.
 

Call the Audit Logs API

Each API request returns a batch of 1000 events, if you need to access more audit events, then you can use pagination. We explain how to use this parameter and its corresponding values at the end of this topic.  

Audit events retrieved from the API are composed of a JSON with standard fields. We describe these in more detail in the section below The Audit Event.

Events are sorted in descending order, starting from most to least recent event, and they’re sorted by the field ingestionTimestamp . The field eventTimestamp represents the timestamp when the event occurred. The maximum lookback period for each API query is 180 days prior to the date of query.

To ensure that you don’t miss any audit events, we recommend that the time ranges for your queries overlap a little. These are defined with the parameter ingestedSince. In the event that you retrieve duplicated events, you can use the unique field eventId to deduplicate your events. 

Here’s the information you need to call the Audit Logs API in Pigment.

Base URL

https://api/audit/v1/events?ingestedSince

HTTP Verb 

GET

API Parameters

You can use the following parameters for the Audit Logs API. They’re both optional:

Sample Query 

GET https://api/audit/v1/events?ingestedSince=2023-11-27

Sample cURL Query 

curl -X GET 'https://pigment.app/api/audit/v1/events?ingestedSince=2023-11-27' \
    -H 'authorization: Bearer XXXX' 

Authentication Header

In this example, xxx is your Audit Logs API key. 

Authorization: Bearer xxx

The Audit Event

When the Audit Logs API is called, the requested audit events are returned as a JSON. The type of returned audit events determine the final format of the JSON.

Here’s some important information about the returned audit events: 

• The API returns a maximum of 1000 audit events per API request.
  You can retrieve more events by using pagination, for more information below. 
• Events are sorted in descending order, starting from most to least recent event.
  These are sorted by the field: ingestionTimestamp 
• A timestamp is indicated for the occurring event.
  This is controlled by the field:  eventTimestamp
• Each event has an earliest possible start date, these are listed below. This is the date when the event was available in the Audit Logs API. 
• Depending on how you query the API, you may fetch duplicate events. You should use the eventId property to deduplicate the events: this is a unique ID for each event.

Every audit event returned by the Audit Logs API has the following standard fields:

a1234567-a123-000a-1234-1234567aa12a

2023-12-07T12:04:31.0146524+00:00

2023-12-07T12:04:31.0287907+00:00

"user":{
   "id":"ABC123",
   "name":"Acme Support",
   "email":"SUPPORT123@AcmeInc.COM",
   "impersonator":{
      "id":"ABC1234",
      "name":"John Doe",
      "email":"John.Doe@AcmeInc.COM"
   },
   "jwt":{
      "id":"ABC1234",
      "issuedAt":"2023-12-20T10:24:58Z",
      "expiresAt":"2023-12-20T14:24:58Z"

"organization":{
   "id":"ABC1234",
   "name":"Acme Inc."
},
"clientContext":{
   "ipAddress":"10.100.100.10",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 99_15_7"
}

"entity": {
"id": "ABC1234",
"name": "My new list",
"application": {
"id": "ABC1234",
"name": "My new app"
},
"entityType": "Dimension"
},
"settings": {
"isSecurityBlock": false
}

actor in the audit event

• Pigment Support as the actor : As part of Pigment Support services, Pigment members are able to impersonate the Pigment Support user account to access your Workspace. The Pigment Support Account will not have UserLoggedIn or UserLoggedOut events. Instead, each time the Pigment Support account starts a session in the workspace, there will be the event SupportSessionStarted. You can use the Audit Logs API to monitor events that are generated by this account, specifically by using the impersonator parameter in the actor payload. 
  Here’s a sample response using this parameter:

"actor": {
				"user": {
					"id": "ABC123",
					"name": "Acme Support",
					"email": "SUPPORT123@AcmeInc.COM",
					"impersonator": {
						"id": "ABC1234",
						"name": "John Doe",
						"email": "John.Doe@AcmeInc.COM"
					},
					"jwt": {
						"id": "ABC1234",
						"issuedAt": "2023-12-20T10:24:58Z",
						"expiresAt": "2023-12-20T14:24:58Z"
					}
				}
			}

• API as the actor: If any events were executed through Pigment API (e.g. Export or User Provisioning), the actor parameter contains a field api with details of the API key that’s used to generate that event:

"api": {
					"apiKeyId": "11111111-a111-1111-111d-11ba11111da1",
					"apiKeyName": "My Export API KEY"
				}

Retrieve Additional Events with Pagination

The Audit Logs API retrieves audit trail events in batches, with each batch size containing 1000 events. The API uses a cursor-based pagination to retrieve additional events per batch. 

A cursor-paginated method returns: 

• a batch of the total set of results
• a cursor that points to the next batch of the results

When there are more than 1000 events available for your API request, the hasMoreEvents parameter in your response payload is set to true: 

{
  "events": [{}],
  "hasMoreEvents": true,
  "nextEventsCursor": "cD0yMDIxLTAxLTA2KzAzAAABM"
}

If you need to retrieve another batch of additional events, you need to do the following:

1. Locate the nextEventsCursor parameter in your response payload, and copy its value. 
2. Create a new API query, appending the cursor parameter and the value provided for nextEventsCursor. 
   
   The examples below use the ingestedSince and cursor parameters.
   
   Here we use the same value that was returned for the nextEventsCursor parameter in the previous example: 
   Sample Query:  
   GET 'https://api/audit/v1/events?ingestedSince=2024-01-11T20:00:00&cursor=cD0yMDIxLTAxLTA2KzAzAAABM'
   
   Sample cURL Query: 
   curl -X GET 'https://pigment.app/api/audit/v1/events?ingestedSince=2023-11-27T15:00:00&cursor=cD0yMDIxLTAxLTA2KzAzAAABM' \     -H 'authorization: Bearer XXXX'
3. Repeat this process for each batch of API events that you need.