List Audit Logs

GET /v1/audit-logs

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

Who sees `details`

details records what changed: before and after values, names, and addresses. It is always sanitised. Values under credential-shaped keys (client_secret, access_token, and so on) read ***REDACTED***, and user:password@ userinfo is removed from any URL. Identifiers are kept, such as the acting key’s api_key_id.

Caller	`details`
API key or OAuth client with `audit_log:list`	Sanitised `details`, `details_redacted: false`
User-bound token (the `knoxcall` CLI, device or authorization-code grant) whose holder is an Admin or Owner	Sanitised `details`, `details_redacted: false`
User-bound token whose holder is a Viewer or Editor	`details: {}` and `details_redacted: true`

The rest of the row (action, resource, IP address and time) is returned to every caller. A redacted details is always an empty object, never a string, so typed clients decode it unchanged. details itself is always an object or null: an entry whose stored details are not a JSON object (a bare string, array or number from a self-hosted agent) is returned sanitised and wrapped as {"value": ...}. The same rule applies to GET /v1/audit-logs/events and to the dashboard’s Audit Trail.

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

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "action": "create",
      "resource_type": "route",
      "resource_id": "rt-uuid-1",
      "details": {
        "name": "Payment Gateway",
        "target_base_url": "***REDACTED***"
      },
      "details_redacted": false,
      "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"
      },
      "details_redacted": false,
      "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"
  }
}

import { KnoxCall } from "@knoxcall/sdk";

const client = new KnoxCall(); // credentials from `knoxcall login` or KNOXCALL_CLIENT_ID / KNOXCALL_CLIENT_SECRET

// List all audit logs
const page = await client.auditLogs.list();
const logs = page.data;

// Filter by action and resource type
const filtered = await client.auditLogs.list({ action: "delete", resource_type: "route" });
const deletions = filtered.data;

from knoxcall import KnoxCall

client = KnoxCall()  # credentials from `knoxcall login` or KNOXCALL_CLIENT_ID / KNOXCALL_CLIENT_SECRET

# List all audit logs
page = client.audit_logs.list()
logs = page["data"]

# Filter by resource type
filtered = client.audit_logs.list(resource_type="secret", per_page=50)
secret_logs = filtered["data"]

# Mint a 1-hour OAuth token (client_credentials) — see /api-reference/authentication
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

# List all audit logs
curl "https://api.knoxcall.com/v1/audit-logs" \
  -H "Authorization: Bearer $TOKEN"

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

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

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.

Overview

Workload Identity

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

List Audit Logs

List Audit Logs

Who sees `details`

Query Parameters

Response

Common Action Types

Common Resource Types

​List Audit Logs

​Who sees details

​Query Parameters

​Response

​Common Action Types

​Common Resource Types

List Audit Logs

Who sees `details`

Query Parameters

Response

Common Action Types

Common Resource Types