> ## 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.

# List Audit Logs

> Returns a paginated list of audit log entries for your tenant configuration changes

## List Audit Logs

```text theme={"dark"}
GET /v1/audit-logs
```

Returns a paginated list of audit log entries, newest first. You can filter by action type and resource type.

### Query Parameters

| Parameter       | Type    | Default | Description                                                                                      |
| --------------- | ------- | ------- | ------------------------------------------------------------------------------------------------ |
| `page`          | integer | `1`     | Page number                                                                                      |
| `per_page`      | integer | `20`    | Items per page (max 100)                                                                         |
| `action`        | string  | --      | Filter by action (e.g., `create`, `update`, `delete`)                                            |
| `resource_type` | string  | --      | Filter by resource type (e.g., `route`, `secret`, `client`, `webhook`, `environment`, `api_key`) |

### Response

```json theme={"dark"}
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "action": "create",
      "resource_type": "route",
      "resource_id": "rt-uuid-1",
      "details": {
        "name": "Payment Gateway",
        "target_base_url": "https://api.stripe.com/v1"
      },
      "ip_address": "203.0.113.42",
      "created_at": "2026-03-10T14:22:01.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "action": "update",
      "resource_type": "secret",
      "resource_id": "sec-uuid-1",
      "details": {
        "field": "value",
        "environment": "production"
      },
      "ip_address": "203.0.113.42",
      "created_at": "2026-03-10T14:20:00.000Z"
    }
  ],
  "meta": {
    "total": 487,
    "page": 1,
    "per_page": 20,
    "total_pages": 25,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

<CodeGroup>
  ```bash cURL theme={"dark"}
  # List all audit logs
  curl "https://api.knoxcall.com/v1/audit-logs" \
    -H "Authorization: Bearer tk_live_abc123..."

  # Filter by action and resource type
  curl "https://api.knoxcall.com/v1/audit-logs?action=delete&resource_type=route" \
    -H "Authorization: Bearer tk_live_abc123..."
  ```

  ```python Python theme={"dark"}
  import requests

  # List all audit logs
  resp = requests.get(
      "https://api.knoxcall.com/v1/audit-logs",
      headers={"Authorization": "Bearer tk_live_abc123..."}
  )
  logs = resp.json()["data"]

  # Filter by resource type
  resp = requests.get(
      "https://api.knoxcall.com/v1/audit-logs",
      params={"resource_type": "secret", "per_page": 50},
      headers={"Authorization": "Bearer tk_live_abc123..."}
  )
  secret_logs = resp.json()["data"]
  ```

  ```javascript Node.js theme={"dark"}
  // List all audit logs
  const resp = await fetch("https://api.knoxcall.com/v1/audit-logs", {
    headers: { Authorization: "Bearer tk_live_abc123..." }
  });
  const { data: logs } = await resp.json();

  // Filter by action
  const filtered = await fetch(
    "https://api.knoxcall.com/v1/audit-logs?action=delete&resource_type=route",
    { headers: { Authorization: "Bearer tk_live_abc123..." } }
  );
  const { data: deletions } = await filtered.json();
  ```
</CodeGroup>

### Common Action Types

Standard CRUD actions appear on any resource type:

| Action    | Description             |
| --------- | ----------------------- |
| `create`  | A resource was created  |
| `update`  | A resource was modified |
| `delete`  | A resource was deleted  |
| `enable`  | A resource was enabled  |
| `disable` | A resource was disabled |
| `revoke`  | An API key was revoked  |

Critical audit chain actions — these go into the separate `audit_log_critical` table (see below):

| Action                            | Description                                                          |
| --------------------------------- | -------------------------------------------------------------------- |
| `byok.kms.onboard`                | Customer KMS provider onboarded (BYOK)                               |
| `byok.kms.rotate`                 | Tenant master key rotated                                            |
| `byok.kms.unseal`                 | Tenant unsealed after KMS access restored                            |
| `byok.kms.revoke`                 | Tenant master key version explicitly revoked (cryptographic erasure) |
| `migration.create`                | Secret store migration created                                       |
| `migration.cancel`                | Migration cancelled                                                  |
| `migration.item.reveal`           | Reviewer revealed plaintext value of a migration item                |
| `migration.item.approve`          | Reviewer approved a migration item                                   |
| `migration.item.reject`           | Reviewer rejected a migration item                                   |
| `migration.item.expire`           | Migration item TTL expired (cron-driven)                             |
| `migration.commit`                | Operator committed the migration as complete                         |
| `migration.credentials.expired`   | Migration provider credentials expired                               |
| `migration.db_proxy_route.create` | DB proxy route created for a migration                               |
| `migration.db_proxy_route.delete` | DB proxy route deleted                                               |
| `tenant.impersonate`              | KnoxCall support admin impersonated a tenant                         |

### Common Resource Types

General audit log resource types:

| Resource Type        | Description                |
| -------------------- | -------------------------- |
| `route`              | API proxy route            |
| `secret`             | Encrypted secret           |
| `client`             | Authorized client          |
| `webhook`            | Webhook configuration      |
| `environment`        | Environment definition     |
| `api_key`            | API key                    |
| `environment_config` | Route environment override |

Critical audit chain resource types (see `audit_log_critical` below):

| Resource Type                  | Description                                |
| ------------------------------ | ------------------------------------------ |
| `tenant_kms_config`            | BYOK KMS configuration                     |
| `tenant_master_key`            | Tenant master key version                  |
| `secret_migration`             | Secret store migration job                 |
| `secret_migration_item`        | Individual item within a migration         |
| `migration_db_proxy_route`     | DB proxy route record for a migration      |
| `migration_credential`         | Provider credential record for a migration |
| `tenant_impersonation_session` | Admin impersonation session                |

<Note>
  Audit log entries are immutable and cannot be modified, but they are pruned according to your subscription plan's data retention policy — a scheduled cleanup deletes `audit_logs` rows older than the plan's retention window. The separate critical audit chain (`audit_log_critical`, see `chain` below) is never pruned and is retained permanently.
</Note>