Audit Logs

Truthlock maintains comprehensive audit logs for security monitoring, compliance reporting, and operational troubleshooting.

What's Logged

Every API operation generates an audit event. This includes successful operations, failed attempts, and security-relevant events.

API Operations

Attestation minting
Attestation revocation
Issuer creation/modification
Key registration

Security Events

Authentication failures
Permission denied
Rate limit exceeded
Suspicious activity

Governance Actions

Issuer approval/rejection
Issuer suspension
Role assignments
API key management

User Activity

User login/logout
Password changes
User invitations
Role changes

Audit Event Structure

Each audit event contains detailed context about what happened, who did it, and when:

{
  "id": "evt_abc123",
  "timestamp": "2026-01-13T12:34:56.789Z",
  "tenant_id": "tenant-uuid",
  "actor": {
    "type": "user",           // or "api_key", "system"
    "id": "user-uuid",
    "email": "admin@example.com",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0..."
  },
  "action": "attestation.mint",
  "resource": {
    "type": "attestation",
    "id": "attestation-uuid"
  },
  "outcome": "success",       // or "failure"
  "details": {
    "issuer_id": "issuer-uuid",
    "subject": "user:12345",
    "claim": "email_verified"
  },
  "error": null               // or error details if failed
}

Querying Audit Logs

Basic Query

curl -X GET "https://api.truthlocks.com/v1/audit/events?limit=100" \
  -H "X-API-Key: tl_live_your_api_key"

Filtered Query

curl -X GET "https://api.truthlocks.com/v1/audit/events" \
  -H "X-API-Key: tl_live_your_api_key" \
  -G \
  --data-urlencode "action=attestation.mint" \
  --data-urlencode "actor.email=admin@example.com" \
  --data-urlencode "start_time=2026-01-01T00:00:00Z" \
  --data-urlencode "end_time=2026-01-31T23:59:59Z" \
  --data-urlencode "limit=50"

Filter Parameters

Parameter	Type	Description
`action`	string	Filter by action type (e.g., `attestation.mint`)
`actor.id`	UUID	Filter by user or API key ID
`actor.email`	string	Filter by actor email
`resource.type`	string	Filter by resource (attestation, issuer, user)
`resource.id`	UUID	Filter by specific resource ID
`outcome`	string	`success` or `failure`
`start_time`	datetime	Events after this time (ISO 8601)
`end_time`	datetime	Events before this time (ISO 8601)
`limit`	integer	Max events to return (default 50, max 1000)
`cursor`	string	Pagination cursor for next page

Common Use Cases

Security Investigation

Find all failed authentication attempts from a specific IP:

GET /v1/audit/events
  ?action=auth.failure
  &actor.ip=203.0.113.42
  &start_time=2026-01-12T00:00:00Z

Compliance Report

Export all attestation operations for a time period:

GET /v1/audit/events
  ?resource.type=attestation
  &start_time=2026-01-01T00:00:00Z
  &end_time=2026-01-31T23:59:59Z
  &limit=1000

User Activity Review

See everything a specific user did:

GET /v1/audit/events
  ?actor.email=employee@example.com
  &limit=100

Log Retention

Tier	Retention Period	Export Format
Free	7 days	JSON only
Starter	30 days	JSON, CSV
Professional	90 days	JSON, CSV, SIEM integration
Enterprise	1 year (custom available)	All formats + real-time streaming

Long-term Storage: For compliance requirements exceeding your tier's retention period, configure SIEM integration to stream logs to your own infrastructure.

SIEM Integration

Enterprise customers can stream audit logs in real-time to external security information and event management (SIEM) systems.

Supported Integrations

Splunk: HTTP Event Collector (HEC)
Datadog: Log Management API
AWS CloudWatch: Logs subscription
Elastic/ELK: Elasticsearch ingest
Webhook: Custom HTTP endpoint

Enterprise Feature: Real-time log streaming requires Enterprise tier. Contact sales for setup assistance.