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
- 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.
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.
You can use the following parameters for the Audit Logs API. They’re both optional:
|This value is a date format. If you don’t provide a value here, then the default value is 180 days prior to the current date. This is converted from your timezone to a UTC timestamp.
|The value for this parameter is provided by the
nextEventsCursor in your API response payload. You use this to to return more events in your API request based on a cursor-pagination method. We explain how to use this parameter and its corresponding value at the end of this topic.
Sample cURL Query
curl -X GET 'https://pigment.app/api/audit/v1/events?ingestedSince=2023-11-27' \
-H 'authorization: Bearer XXXX'
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:
- A timestamp is indicated for the occurring event.
This is controlled by the field:
- 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
eventIdproperty 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:
|The unique identifier assigned to the audit event.
|Timestamp in UTC format of when the event occurred.
Timestamp in UTC format of when the event was ingested on the event stream.
This may be a different value from the
Details of the user who generated the event.
This is always a user on a Workspace, and is identified by the user ID.
If the actor is indicated as the Pigment Support account, then you see the user’s details who was impersonating the Pigment Support account. More information on
The workspace or organization in which the actor generated the event.
This also contains additional user details, for example, browser and IP address.
The type of audit event that occurred.
More information on the different event types are provided in this article Audit Logs API Events and Event Types.
This information in this field can vary depending on the
The payload contains some standard fields:
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
UserLoggedOutevents. 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
impersonatorparameter in the
Here’s a sample response using this parameter:
"name": "Acme Support",
"name": "John Doe",
- API as the
actor: If any events were executed through Pigment API (e.g. Export or User Provisioning), the actor parameter contains a field
apiwith details of the API key that’s used to generate that event:
"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
If you need to retrieve another batch of additional events, you need to do the following:
- Locate the
nextEventsCursorparameter in your response payload, and copy its value.
- Create a new API query, appending the
cursorparameter and the value provided for
The examples below use the
Here we use the same value that was returned for the
nextEventsCursorparameter in the previous example:
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'
- Repeat this process for each batch of API events that you need.