AuditService

Provides read access to the append-only audit trail. Every significant platform action (campaign created, message sent, user invited, role changed, etc.) is recorded as an immutable, hash-chained event for tamper detection and compliance.

All RPCs are admin-only and extract org_id from the JWT — it is never sent in request messages.

Methods

Method	Description
ListAuditEvents	List audit events with optional filtering
ExportAuditTrail	Export the audit trail to S3 in CSV, JSON, or Parquet format

ListAuditEvents

List audit events with optional filtering by event type, actor, and date range. Results are ordered by created_at descending (newest first).

Authorization: Admin only

Request: ListAuditEventsRequest

Field	Type	Description
page_token	string	Pagination token from a previous response.
page_size	int32	Maximum number of events to return. Min 1, max 100. Default 50.
event_type	AuditEventType	Optional filter: only return events of this type.
actor_id	string	Optional filter: only return events by this actor. UUID format.
start_time	Timestamp	Optional filter: events after this timestamp (inclusive).
end_time	Timestamp	Optional filter: events before this timestamp (exclusive).

Response: ListAuditEventsResponse

Field	Type	Description
events	AuditEvent[]	Audit events matching the request filters.
next_page_token	string	Token for fetching the next page. Empty when no more events.

Example

TypeScript (Connect-Web)

const response = await auditClient.listAuditEvents({
  pageSize: 25,
  eventType: AuditEventType.CAMPAIGN_CREATED,
  startTime: Timestamp.fromDate(new Date("2026-01-01")),
});

for (const event of response.events) {
  console.log(event.id, event.eventType, event.createdAt);
}

Go (gRPC)

resp, err := auditClient.ListAuditEvents(ctx, &pidgrv1.ListAuditEventsRequest{
    PageSize:  25,
    EventType: pidgrv1.AuditEventType_AUDIT_EVENT_TYPE_CAMPAIGN_CREATED,
    StartTime: timestamppb.New(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)),
})
for _, event := range resp.Events {
    fmt.Println(event.Id, event.EventType, event.CreatedAt)
}

ExportAuditTrail

Export the audit trail to S3 in CSV, JSON, or Parquet format. This is an async operation — it returns immediately with PENDING status. Poll or check back later for the download URL.

Authorization: Admin only

Request: ExportAuditTrailRequest

Field	Type	Description
format	AuditExportFormat	Export format: CSV, JSON, or PARQUET.
start_time	Timestamp	Optional: export events after this timestamp.
end_time	Timestamp	Optional: export events before this timestamp.

Response: ExportAuditTrailResponse

Field	Type	Description
export_url	string	Pre-signed S3 URL to download the exported audit trail. Only populated when status is COMPLETED.
status	PrivacyRequestStatus	Current status of the export: PENDING, PROCESSING, COMPLETED, or FAILED.

Example

TypeScript (Connect-Web)

const response = await auditClient.exportAuditTrail({
  format: AuditExportFormat.CSV,
  startTime: Timestamp.fromDate(new Date("2026-01-01")),
  endTime: Timestamp.fromDate(new Date("2026-03-01")),
});

console.log(response.status); // PENDING

Go (gRPC)

resp, err := auditClient.ExportAuditTrail(ctx, &pidgrv1.ExportAuditTrailRequest{
    Format:    pidgrv1.AuditExportFormat_AUDIT_EXPORT_FORMAT_CSV,
    StartTime: timestamppb.New(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)),
    EndTime:   timestamppb.New(time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC)),
})
fmt.Println(resp.Status) // PENDING

AuditEvent Message

An immutable, hash-chained record of a significant platform action. Audit events are append-only — they cannot be updated or deleted. Each event includes a SHA-256 hash linking it to the previous event, forming a tamper-evident chain.

Field	Type	Description
id	string	Unique identifier. UUID format.
org_id	string	Organization in which the event occurred. UUID format.
actor_id	string	User who performed the action. Empty for system-initiated events. UUID format.
event_type	AuditEventType	Type of action that was performed.
entity_type	string	Type of entity affected (e.g., "campaign", "user", "template"). Max 50 characters.
entity_id	string	Identifier of the entity affected. UUID format.
metadata	map<string, string>	Additional context (e.g., old/new values for changes). Max 20 pairs, keys max 50 chars, values max 500 chars.
previous_hash	string	SHA-256 hash of the previous event in the chain. Empty for the first event.
hash	string	SHA-256 hash of this event (previous_hash + event data) for tamper detection.
created_at	Timestamp	Timestamp when the event was recorded.

AuditEventType Enum

Value	Description
CAMPAIGN_CREATED	A campaign was created.
MESSAGE_SENT	A message was sent to a recipient.
MESSAGE_OPENED	A message was opened by a recipient.
ACK_REGISTERED	A recipient acknowledged a campaign.
ESCALATION_EXECUTED	An escalation was triggered by the workflow.
USER_INVITED	A user was invited to the organization.
USER_DEACTIVATED	A user was deactivated.
DATA_EXPORT_REQUESTED	A data export was requested (GDPR Art. 15).
DATA_DELETION_REQUESTED	A data deletion was requested (GDPR Art. 17).
ROLE_CHANGED	A user’s role was changed.
SSO_CONFIGURED	An SSO provider was configured.

AuditExportFormat Enum

Value	Description
CSV	Comma-separated values.
JSON	JSON lines format.
PARQUET	Apache Parquet columnar format.