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

# Audit Logs

> Track all configuration changes to routes, secrets, clients, environments, and alerts. See who made what changes when for compliance and troubleshooting.

# Audit Logs

Track every configuration change made in KnoxCall with complete audit trail for compliance, security, and troubleshooting.

## Critical Audit Chain

For sensitive operations — BYOK KMS management, secret store migrations, and tenant impersonation — KnoxCall maintains a **separate append-only audit log** (`audit_log_critical`) in addition to the standard audit trail.

Entries in the critical chain are:

* **SHA-256 hash-linked** — each entry includes a `prev_hash` (SHA-256 of the prior entry's canonical bytes) and a monotonic `sequence_number`. Tampering with any entry breaks its hash and every subsequent `prev_hash` link, making the tampered row identifiable.
* **Append-only forever** — database triggers prevent UPDATE and DELETE at the Postgres level. There is no retention pruning on this table.
* **Serialized writes** — an advisory lock on every write ensures monotonic, gap-free `sequence_number` values; a gap indicates a deletion attempt.

This chain covers all 15 actions across five domains:

| Domain                   | Actions                                                                                             |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| BYOK KMS                 | `byok.kms.onboard`, `byok.kms.rotate`, `byok.kms.unseal`, `byok.kms.revoke`                         |
| Migration lifecycle      | `migration.create`, `migration.cancel`, `migration.commit`, `migration.credentials.expired`         |
| Migration item review    | `migration.item.reveal`, `migration.item.approve`, `migration.item.reject`, `migration.item.expire` |
| Migration infrastructure | `migration.db_proxy_route.create`, `migration.db_proxy_route.delete`                                |
| Impersonation            | `tenant.impersonate`                                                                                |

For the full chain schema, canonical serialization spec, and verification endpoint, see the [Audit Logs API reference](/api-reference/audit-logs#sha-256-hash-chain--critical-audit-chain).

## Overview

**Audit Logs** record all changes to your KnoxCall configuration:

* 👤 Who made the change (user email)
* 📝 What was changed (resource type and name)
* ⏰ When it happened (timestamp)
* 🔄 What changed (before/after values)
* 🎯 Action performed (create, update, delete, enable, disable)

**Not the same as API Logs:**

* **API Logs** = Requests proxied through routes
* **Audit Logs** = Changes to KnoxCall configuration

## What's Tracked

### Routes

* ✅ Route created
* ✏️ Route updated (target URL, headers, body, etc.)
* 🗑️ Route deleted
* 🔓 Route enabled/disabled
* 🔄 Route duplicated

### Secrets

* ✅ Secret created
* 🔄 Secret version added (rotation)
* ✏️ Secret name updated
* 🗑️ Secret deleted

### Clients

* ✅ Client created (IP address added)
* ✏️ Client updated (IP changed, type changed)
* 🗑️ Client deleted
* 🔓 Client enabled/disabled
* 🔗 Client assigned to route
* ❌ Client unassigned from route

### Environments

* ✅ Environment created
* ✏️ Environment updated (overrides changed)
* 🗑️ Environment deleted
* 🔄 Environment duplicated

### Alerts

* ✅ Alert created
* ✏️ Alert updated (conditions, channels)
* 🗑️ Alert deleted
* 🔓 Alert enabled/disabled

### API Keys

* ✅ API key created
* 🗑️ API key revoked

### Tenant Settings

* ✏️ Tenant name/slug updated
* ⚙️ Feature settings changed

### Team Members

* ✅ Team member invited
* 🗑️ Team member removed
* ✏️ Team member role changed

### Tenant KMS / BYOK

* 🔑 Customer KMS provider onboarded (`byok.kms.onboard`)
* 🔄 Tenant master key rotated (`byok.kms.rotate`)
* 🔓 Tenant unsealed (`byok.kms.unseal`)
* 💣 Tenant master key version revoked — cryptographic erasure (`byok.kms.revoke`)

### Secret Store Migrations

* ✅ Migration created (`migration.create`)
* ❌ Migration cancelled (`migration.cancel`)
* 🔍 Migration item plaintext revealed to reviewer (`migration.item.reveal`)
* ✔️ Migration item approved by reviewer (`migration.item.approve`)
* ✘ Migration item rejected by reviewer (`migration.item.reject`)
* ⏱️ Migration item expired after 7-day TTL (`migration.item.expire`)
* ✅ Migration committed as complete (`migration.commit`)
* 🔌 DB proxy route created for migration (`migration.db_proxy_route.create`)
* 🗑️ DB proxy route deleted (`migration.db_proxy_route.delete`)

### Tenant Impersonation

* 👤 Admin impersonated tenant (`tenant.impersonate`) — support actions only

## Viewing Audit Logs

### Step 1: Navigate to Audit Logs

1. Click **Logs** in the sidebar
2. Select **Audit Logs**
3. See recent changes (most recent first)

### Step 2: Use Filters

**Filter by Action:**

```text theme={"dark"}
☐ Create
☐ Update
☐ Delete
☐ Enable
☐ Disable
```

**Filter by Resource Type:**

```text theme={"dark"}
☐ Route
☐ Secret
☐ Client
☐ Environment
☐ Alert
☐ API Key
☐ Tenant
☐ Team Member
☐ Tenant KMS Config
☐ Migration
```

**Filter by User:**
Search by email address

**Filter by Resource Name:**
Search for specific route, secret, etc.

**Filter by Environment:**
Show changes to specific environment

**Filter by Client/Secret:**
Show changes related to specific client or secret

### Step 3: View Change Details

**Click any audit log entry** to see full details:

**Overview:**

```text theme={"dark"}
Action: Route Updated
Resource: stripe-payments (route_abc123)
User: john@example.com
Timestamp: 2025-01-15 10:30:45 EST
```

**Changes (diff view):**

```diff theme={"dark"}
target_url:
- https://api.stripe.com/v1/charges
+ https://api.eu.stripe.com/v1/charges

inject_headers_json:
  Authorization:
-   Bearer {{secret:stripe-test-key}}
+   Bearer {{secret:stripe-prod-key}}
```

**Context:**

```text theme={"dark"}
IP Address: 203.45.67.89
User Agent: Mozilla/5.0 (Windows NT 10.0)
Session ID: sess_xyz789
```

## Common Use Cases

### Use Case 1: Troubleshooting Configuration Issues

**Scenario:** Route suddenly stopped working

**Investigation:**

1. Navigate to Audit Logs
2. Filter by Resource Type: Route
3. Filter by Resource Name: broken-route
4. See recent changes:
   ```
   2 hours ago: john@example.com updated target_url
   Old: https://api.service.com/v1
   New: https://api.service.com/v2 (typo: should be v1)
   ```
5. Identify issue: Incorrect URL
6. Fix: Revert URL to v1

### Use Case 2: Security Audit

**Scenario:** Quarterly compliance audit

**Steps:**

1. Export audit logs for last 90 days
2. Filter by Action: Delete, Disable
3. Review all deletions/disablements
4. Verify authorized by appropriate users
5. Document for auditor

### Use Case 3: Secret Rotation Tracking

**Scenario:** Verify secrets rotated per policy

**Steps:**

1. Filter by Resource Type: Secret
2. Filter by Action: Update (new version)
3. Check last rotation date for each secret
4. Identify secrets due for rotation
5. Rotate overdue secrets

### Use Case 4: Unauthorized Changes

**Scenario:** Suspect unauthorized configuration changes

**Steps:**

1. Filter by User: (specific team member)
2. Review all changes by that user
3. Check timestamps (after hours?)
4. Verify changes were authorized
5. Take action if unauthorized

### Use Case 5: Change Correlation

**Scenario:** Error rate spiked, find related change

**Steps:**

1. Note time of spike: 10:30 AM
2. Filter audit logs by time: 10:00-10:45 AM
3. See changes during that window:
   ```
   10:25 AM: sarah@example.com updated stripe-payments route
   Changed: rate_limit from 100/min to 10/min
   ```
4. Identified: Rate limit too restrictive
5. Fix: Revert rate limit

## Deep Links

**Jump to audit logs from:**

**Route Details:**

* "View History" button → Audit logs for that route

**Secret Details:**

* "View History" button → Secret rotation history

**Client Details:**

* "View History" button → Client assignment changes

**Alert Details:**

* "View History" button → Alert configuration changes

## Audit Log Entry Details

### Full Information Captured

**User context:**

* Email address
* User ID
* IP address (where request originated)
* Session ID

**Resource context:**

* Resource type (route, secret, client, etc.)
* Resource ID
* Resource name
* Tenant ID

**Change details:**

* Action (create, update, delete, etc.)
* Timestamp (with timezone)
* Before values (for updates)
* After values (for updates)
* Full diff (JSON format)

**Example JSON:**

```json theme={"dark"}
{
  "id": "audit_abc123",
  "action": "update",
  "resource_type": "route",
  "resource_id": "route_xyz789",
  "resource_name": "stripe-payments",
  "user_id": "user_def456",
  "user_email": "john@example.com",
  "timestamp": "2025-01-15T15:30:45Z",
  "ip_address": "203.45.67.89",
  "changes": {
    "target_url": {
      "old": "https://api.stripe.com/v1",
      "new": "https://api.eu.stripe.com/v1"
    },
    "rate_limit_requests": {
      "old": 100,
      "new": 150
    }
  }
}
```

## Export Options

### CSV Export (Pro/Enterprise Only)

**What's exported:**

* Timestamp
* User email
* Action
* Resource type
* Resource name
* Summary of changes

**Steps:**

1. Apply filters to select logs
2. Click **Export** button
3. CSV downloads automatically

**File name format:**

```text theme={"dark"}
audit-logs-{tenant-slug}-{timestamp}.csv
```

### JSON Export (Enterprise Only)

**Full audit trail:**

* Complete JSON for each entry
* Includes before/after values
* All metadata preserved

**Use case:** Import to SIEM tools, compliance systems

## Retention Policies

**By subscription plan (standard `audit_logs` table):**

| Plan       | Retention Period                                                         |
| ---------- | ------------------------------------------------------------------------ |
| Free       | 7 days                                                                   |
| Starter    | 7 days                                                                   |
| Pro        | 30 days                                                                  |
| Enterprise | 90 days (extensible per contract — 12 months or 7 years for HIPAA/SOC 2) |

Older rows are pruned by a daily cron. The hash chain remains intact across pruning — rows are removed from the oldest end only, so verification of remaining rows continues to work.

**Critical audit chain (`audit_log_critical`):** Not pruned. Records persist indefinitely regardless of plan. Export to long-term storage if needed before tenant deletion.

**After standard retention:**

* Audit logs automatically deleted
* Export before expiration for permanent records

## Compliance Features

### SOC 2 / ISO 27001 Requirements

**Audit logs support:**

* ✅ Who: User identification
* ✅ What: Resource and action
* ✅ When: Timestamp with timezone
* ✅ How: Change details (before/after)
* ✅ Integrity: Immutable (cannot be edited)
* ✅ Export: CSV/JSON for auditors

### GDPR Compliance

**Data captured:**

* User email addresses (can be pseudonymized)
* IP addresses (can be anonymized)
* Configuration changes (no PII)

**Data deletion:**

* Audit logs deleted per retention policy
* Can export before deletion

## Best Practices

### 1. Regular Review

**Weekly:**

* Review all changes
* Verify authorized
* Identify unauthorized activity

**Monthly:**

* Export audit logs
* Archive for compliance
* Review trends

### 2. Document Standard Changes

**Create change log:**

```text theme={"dark"}
2025-01-15:
- Updated stripe-payments target URL for EU region
- Rotated stripe-prod-key secret (scheduled)
- Added client: production-server-03
```

**Cross-reference with audit logs** for verification.

### 3. Monitor High-Risk Actions

**Focus on:**

* Deletions (routes, secrets, clients)
* Disablements (routes, alerts)
* Secret rotations (ensure scheduled)
* API key revocations (verify authorized)

### 4. Use Filters for Investigations

**Start broad, narrow down:**

1. All changes today
2. Filter by resource type (e.g., routes)
3. Filter by specific route
4. View detailed changes

### 5. Export for Compliance

**Quarterly/Annual:**

1. Export full audit log history
2. Store securely (encrypted)
3. Provide to auditors when required
4. Maintain for legal retention period

## Troubleshooting

### Issue: "Audit log missing"

**Causes:**

* Change happened before audit logging enabled
* Entry expired (past retention period)
* System issue (rare)

**Check:**

* Verify retention period
* Confirm timestamp within retention

### Issue: "Can't see changes by other users"

**Cause:** You might be filtering by your user

**Fix:** Clear user filter to see all users

### Issue: "Export button disabled"

**Cause:** Starter plan (export requires Pro/Enterprise)

**Fix:** Upgrade subscription plan

### Issue: "Diff not showing"

**Cause:** Change type doesn't support diff (e.g., delete action)

**Expected:** Create and Delete actions don't have before/after diff

## Related Features

* **API Logs**: Track API request activity (different from config changes)
* **Alerts**: Set up alerts for specific configuration changes (coming soon)
* **Team Management**: Control who can make changes

## Next Steps

<CardGroup cols={2}>
  <Card title="API Logs" icon="list" href="/monitoring/api-logs">
    View API request logs
  </Card>

  <Card title="Team Management" icon="users" href="/account/team-collaboration">
    Manage team access
  </Card>

  <Card title="Routes" icon="route" href="/getting-started/first-route">
    Configure routes
  </Card>

  <Card title="Secrets" icon="key" href="/getting-started/first-secret">
    Manage secrets
  </Card>
</CardGroup>

***

<CardGroup cols={2}>
  <Card title="📊 Statistics" icon="chart-line">
    * **Level**: beginner
    * **Time**: 10 minutes
  </Card>

  <Card title="🏷️ Tags" icon="tags">
    `audit`, `compliance`, `security`, `tracking`, `governance`
  </Card>
</CardGroup>