Audit Logs

Truthlocks 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",
  "actor_id": "user-uuid",
  "action": "attestation.mint",
  "resource_type": "attestation",
  "resource_id": "attestation-uuid",
  "service": "trust-registry",
  "outcome": "SUCCESS",
  "metadata": {
    "issuer_id": "issuer-uuid",
    "subject": "user:12345",
    "claim": "email_verified"
  },
  "integrity_hash": "sha256:abc123..."
}

Field	Type	Description
`actor_type`	string	Who performed the action: `USER`, `API_KEY`, or `SERVICE`
`actor_id`	string	UUID of the user, API key, or service that triggered the event
`action`	string	The operation performed (e.g., `attestation.mint`)
`resource_type`	string	Type of resource affected (e.g., `attestation`, `issuer`, `user`)
`resource_id`	string	UUID of the affected resource
`service`	string	The backend service that handled the request (e.g., `trust-registry`, `audit-service`)
`outcome`	string	`SUCCESS` or `FAILURE`
`metadata`	object	Action-specific context such as issuer ID, claim type, or error details
`integrity_hash`	string	SHA-256 hash for tamper-evidence verification

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_id=user-uuid" \
  --data-urlencode "from=2026-01-01T00:00:00Z" \
  --data-urlencode "to=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`	string	Filter by user or API key ID
`resource_type`	string	Filter by resource (attestation, issuer, user)
`from`	datetime	Events after this time (ISO 8601)
`to`	datetime	Events before this time (ISO 8601)
`limit`	integer	Max events to return (default 50, max 1000)
`cursor`	string	Pagination cursor for next page

Policy decision audit trail

Every issuance policy evaluation is automatically recorded as an audit event. Each record captures the decision_id, policy version, matched rules, evaluation time, and a SHA-256 hash of the input for tamper-evidence. Query policy decisions by filtering on resource_type=policy_decision:

curl "https://api.truthlocks.com/v1/audit/events?resource_type=policy_decision&resource_id=dec_7f3a1b" \
  -H "X-API-Key: tl_live_..."

See decision audit trail for the full list of recorded fields.

Common use cases

Security investigation

Find all failed authentication attempts for a specific actor:

GET /v1/audit/events
  ?action=auth.failure
  &actor_id=user-uuid
  &from=2026-01-12T00:00:00Z

Compliance Report

Export all attestation operations for a time period:

GET /v1/audit/events
  ?resource_type=attestation
  &from=2026-01-01T00:00:00Z
  &to=2026-01-31T23:59:59Z
  &limit=1000

User Activity Review

See everything a specific user did:

GET /v1/audit/events
  ?actor_id=employee-uuid
  &limit=100

Log retention

Tier	Default retention	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

For compliance requirements exceeding your tier’s retention period, configure SIEM integration to stream logs to your own infrastructure.

Custom retention policies

You can configure how long audit logs are retained and whether expired logs are archived or permanently deleted. Set retention policies globally or per environment.

Field	Type	Description
`retention_days`	integer	Days to keep audit logs (30–3,650)
`hard_delete`	boolean	If `true`, permanently delete expired logs. If `false`, archive them.
`export_allowed`	boolean	Whether audit exports are permitted for this scope
`environment_id`	string	Optional. Apply this policy to a specific environment only.

The default policy retains logs for 365 days, archives (soft-deletes) expired logs, and allows exports. Get your current retention policy:

curl https://api.truthlocks.com/v1/audit/retention \
  -H "X-API-Key: tl_live_..."

{
  "retention_days": 365,
  "hard_delete": false,
  "export_allowed": true,
  "environment_id": null
}

Update the retention policy:

curl -X PUT https://api.truthlocks.com/v1/audit/retention \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "retention_days": 730,
    "hard_delete": false,
    "export_allowed": true
  }'

When an environment-specific policy exists, it takes precedence over the global policy. If no environment-specific policy is set, the global policy applies.

Changing hard_delete to true permanently removes logs once they pass the retention window. This action cannot be undone. Make sure you have exported any logs you need before enabling hard delete.

Updating retention settings requires the tenant.audit.retention.manage permission. Viewing settings requires tenant.audit.retention.read.

SIEM Integration

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

Supported providers

Provider	Transport	Format
Splunk	HTTP Event Collector (HEC)	JSON
Datadog	Log Management API	JSON
AWS CloudWatch	Logs subscription	JSON
Elastic/ELK	Elasticsearch ingest	JSON
Custom webhook	HTTP POST	JSON

Configure a streaming destination from Settings > Audit > SIEM in the console, or manage destinations programmatically through the SIEM configuration API. For step-by-step provider setup instructions, see the SIEM integration guide.

Create a SIEM destination

curl -X POST https://api.truthlocks.com/v1/audit/siem \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "splunk",
    "endpoint": "https://hec.splunk.example.com:8088/services/collector",
    "token": "your-hec-token",
    "enabled": true
  }'

{
  "id": "siem_abc123",
  "provider": "splunk",
  "endpoint": "https://hec.splunk.example.com:8088/services/collector",
  "enabled": true,
  "created_at": "2026-06-30T12:00:00Z",
  "status": "active"
}

Replace provider with one of splunk, datadog, cloudwatch, elastic, or webhook. Each provider requires a destination endpoint and an authentication credential (token for Splunk, Datadog, and Elastic; access_key_id and secret_access_key for CloudWatch; secret for custom webhooks).

List SIEM destinations

Retrieve all configured streaming destinations for your tenant.

curl https://api.truthlocks.com/v1/audit/siem \
  -H "X-API-Key: tl_live_..."

Update a SIEM destination

Change the endpoint, credentials, or enabled state of an existing destination.

curl -X PUT https://api.truthlocks.com/v1/audit/siem/siem_abc123 \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://hec-new.splunk.example.com:8088/services/collector",
    "token": "your-new-hec-token",
    "enabled": true
  }'

Delete a SIEM destination

Remove a streaming destination. In-flight events are flushed before the destination is deleted.

curl -X DELETE https://api.truthlocks.com/v1/audit/siem/siem_abc123 \
  -H "X-API-Key: tl_live_..."

Delivery and buffering

Once enabled, every audit event is streamed to your destination in real time alongside the standard in-platform log. If the destination is unreachable, events are buffered and retried with exponential backoff for up to 24 hours. You can monitor delivery health in the status field returned by the list endpoint — possible values are active, degraded (retrying), and failed.

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

Next steps

SIEM integration

Stream audit events to Splunk, Datadog, CloudWatch, Elastic, or a custom webhook.

Compliance exports

Export audit data in SOC 2, GDPR, and HIPAA formats.

Abuse hardening

Detect and prevent abuse using audit data.

Rate limits

Understand rate limiting behavior in audit logs.

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

What’s Logged

API Operations

Security Events

Governance Actions

User Activity

Audit Event Structure

Querying Audit Logs

Basic Query

Filtered Query

Filter Parameters

Policy decision audit trail

Common use cases

Security investigation

Compliance Report

User Activity Review

Log retention

Custom retention policies

SIEM Integration

Supported providers

Create a SIEM destination

List SIEM destinations

Update a SIEM destination

Delete a SIEM destination

Delivery and buffering

Next steps

SIEM integration

Compliance exports

Abuse hardening

Rate limits

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

Documentation Index

​What’s Logged

API Operations

Security Events

Governance Actions

User Activity

​Audit Event Structure

​Querying Audit Logs

​Basic Query

​Filtered Query

​Filter Parameters

​Policy decision audit trail

​Common use cases

​Security investigation

​Compliance Report

​User Activity Review

​Log retention

​Custom retention policies

​SIEM Integration

​Supported providers

​Create a SIEM destination

​List SIEM destinations

​Update a SIEM destination

​Delete a SIEM destination

​Delivery and buffering

​Next steps

SIEM integration

Compliance exports

Abuse hardening

Rate limits

What’s Logged

Audit Event Structure

Querying Audit Logs

Basic Query

Filtered Query

Filter Parameters

Policy decision audit trail

Common use cases

Security investigation

Compliance Report

User Activity Review

Log retention

Custom retention policies

SIEM Integration

Supported providers

Create a SIEM destination

List SIEM destinations

Update a SIEM destination

Delete a SIEM destination

Delivery and buffering

Next steps