> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Logs

> Track all API activity, security events, and compliance auditing.

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.

<CardGroup cols={2}>
  <Card title="API Operations" icon="server">
    * Attestation minting \* Attestation revocation \* Issuer
      creation/modification \* Key registration
  </Card>

  <Card title="Security Events" icon="shield-halved">
    * Authentication failures \* Permission denied \* Rate limit exceeded \*
      Suspicious activity
  </Card>

  <Card title="Governance Actions" icon="building-columns">
    * Issuer approval/rejection \* Issuer suspension \* Role assignments \* API key
      management
  </Card>

  <Card title="User Activity" icon="user">
    * User login/logout \* Password changes \* User invitations \* Role changes
  </Card>
</CardGroup>

## Audit Event Structure

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

```json theme={null}
{
  "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

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

### Filtered Query

```bash theme={null}
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](/guides/issuance-policies) 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`:

```bash theme={null}
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](/guides/issuance-policies#decision-audit-trail) for the full list of recorded fields.

## Common use cases

### Security investigation

Find all failed authentication attempts for a specific actor:

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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 |

<Info>
  For compliance requirements exceeding your tier's
  retention period, configure SIEM integration to stream logs to your own
  infrastructure.
</Info>

### 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:**

```bash theme={null}
curl https://api.truthlocks.com/v1/audit/retention \
  -H "X-API-Key: tl_live_..."
```

```json theme={null}
{
  "retention_days": 365,
  "hard_delete": false,
  "export_allowed": true,
  "environment_id": null
}
```

**Update the retention policy:**

```bash theme={null}
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.

<Warning>
  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.
</Warning>

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](/api-reference/audit/siem/create). For step-by-step provider setup instructions, see the [SIEM integration guide](/guides/siem-integration).

### Create a SIEM destination

```bash theme={null}
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
  }'
```

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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`.

<Warning>
  **Enterprise feature:** Real-time log streaming requires the Enterprise tier.
  Contact sales for setup assistance.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="SIEM integration" icon="tower-broadcast" href="/guides/siem-integration">
    Stream audit events to Splunk, Datadog, CloudWatch, Elastic, or a custom webhook.
  </Card>

  <Card title="Compliance exports" icon="file-export" href="/guides/compliance-exports">
    Export audit data in SOC 2, GDPR, and HIPAA formats.
  </Card>

  <Card title="Abuse hardening" icon="shield-virus" href="/security/abuse-hardening">
    Detect and prevent abuse using audit data.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/ops/limits">
    Understand rate limiting behavior in audit logs.
  </Card>
</CardGroup>