API Access Log Auditing: Evidence, Integrity, Retention, and Review

An API gateway can record who called which route, when, from where, and with what transport-level outcome. That makes gateway access logs valuable audit evidence, but not a complete audit trail. The gateway usually cannot know whether an application changed the intended business object, approved a payment, or exported the expected rows. Combine gateway events with identity-provider, policy-decision, application, and data-store events through a stable correlation identifier.

Auditability comes from an explicit event contract, protected delivery, controlled access, retention, review, and tested reconstruction. Enabling a logging plugin is only the first step; it does not make records complete, durable, or tamper-proof.

Key Takeaways

• Separate high-volume access telemetry from the smaller set of events retained as audit evidence.
• Record actor, action, resource, outcome, reason, time, policy version, and correlation context.
• Treat client-supplied identity and forwarding headers as untrusted until a trusted component verifies or overwrites them.
• Minimize payloads and credentials; an audit store is sensitive security data, not a copy of every request.
• Test gaps, duplicates, clock skew, collector outages, unauthorized reads, retention, and reconstruction.

Distinguish Access Logs from Audit Evidence

Access logs answer transport questions: which route matched, how long the request took, which status code was returned, and which upstream handled it. Audit evidence supports a later determination about a sensitive action: who attempted what operation on which resource, under which policy, and with what result.

The two overlap, but they are not interchangeable:

The OWASP Logging Cheat Sheet notes that application code has identity, permission, target, action, and outcome context that infrastructure logs may not have. Use the gateway as one evidence producer, not as the sole witness.

Define the Event Contract First

For each auditable action, define the minimum fields and their trust source:

• When: event time in UTC, ingestion time, and clock-confidence or offset when relevant.
• Where: environment, gateway instance, route or service ID, API version, and region.
• Who: verified user, client, workload, consumer, or tenant identifier; authentication method; never a raw secret.
• What: normalized action, resource type and identifier, HTTP method, and matched route.
• Decision: allow or deny, policy and version, reason code, and decision-point identity.
• Outcome: gateway status plus the application's business result when those differ.
• Correlation: request ID, trace ID, or workflow ID that joins gateway, policy, application, and data events.
• Governance: schema version, data classification, retention class, and evidence source.

Do not use a caller-provided X-User-ID, tenant header, or X-Forwarded-For as verified identity merely because it exists. Record the value as untrusted input or replace it at the trusted authentication and proxy boundary.

Minimize Sensitive Data

Audit records should normally identify the action without storing the full request or response body. Bodies can contain passwords, tokens, payment data, health data, uploaded files, or personal information unrelated to the audit purpose.

Prefer stable internal identifiers, bounded reason codes, field names that changed, and cryptographic hashes only when their use is justified. Do not log:

• passwords, private keys, session identifiers, or bearer tokens;
• full Authorization, cookie, or API-key headers;
• entire payloads by default;
• secrets embedded in URLs or query strings;
• data outside the audit store's approved classification.

Redaction must happen before untrusted data reaches downstream queues and stores. Also sanitize CR, LF, delimiters, and control characters so an attacker cannot forge extra log records or corrupt parsing.

Export Structured APISIX Events

Apache APISIX 3.18 documents the http-logger plugin for sending JSON request and response logs to an HTTP(S) collector in batches. It supports a custom log_format; request and response bodies are disabled by default.

The following illustrative route exports a deliberately small access record. It is reviewable configuration, not a complete audit system:

{
  "uri": "/v1/admin/*",
  "plugins": {
    "request-id": {
      "include_in_response": true
    },
    "http-logger": {
      "uri": "https://audit-collector.internal/v1/events",
      "ssl_verify": true,
      "log_format": {
        "schema_version": "gateway-audit-1",
        "event_time": "$time_iso8601",
        "request_id": "$apisix_request_id",
        "route_id": "$route_id",
        "consumer": "$consumer_name",
        "method": "$request_method",
        "path": "$uri",
        "status": "$status",
        "client_address": "$remote_addr"
      },
      "include_req_body": false,
      "include_resp_body": false
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {"admin-api.internal:8443": 1}
  }
}

The request-id plugin exposes its value as $apisix_request_id and can preserve a caller-supplied X-Request-Id. Treat this value as correlation context, not trusted identity. Confirm every variable and plugin field against the documentation for the APISIX release you deploy. Use authenticated TLS to the collector, restrict network access, and manage collector credentials through the deployment's secret workflow. An APISIX batch logger transports records; the receiving pipeline still owns durable acknowledgement, deduplication, indexing, retention, and evidence protection.

Protect the Evidence Pipeline

Design the path as a security boundary:

flowchart LR
    C[Client] --> G[API gateway]
    G --> A[Application]
    G --> Q[Authenticated collector]
    A --> Q
    P[Identity and policy services] --> Q
    Q --> S[(Restricted audit store)]
    S --> R[Approved review and investigation]

• Give producers append-only or narrowly scoped write access; do not let request-processing identities alter retained records.
• Encrypt transport and storage, and separate read, export, retention, and deletion privileges.
• Detect missing sequence ranges, ingestion delay, schema rejection, unauthorized access, and retention-policy changes.
• Use immutable or write-once controls where the risk model requires them, while preserving an approved legal deletion path.
• Version schemas and policy identifiers so an investigator can interpret old decisions after configuration changes.
• Document whether a collector outage drops, buffers, or blocks records. Avoid turning a general logging dependency into an uncontrolled API outage.

Hash chains or signatures can help detect modification, but they do not prove that every required event was generated. Completeness needs coverage tests, pipeline monitoring, and reconciliation against authoritative business records.

Set Retention and Access by Purpose

Retention is not “keep everything forever.” Define it by legal, regulatory, contractual, security, and operational purpose. Different event classes can require different periods. Record the policy owner, start point, hold process, archive format, deletion method, and evidence that disposal occurred.

Audit-store access is itself an auditable action. Require least privilege, approval for broad exports, query logging, alerting on unusual downloads, and periodic access review. Keep investigation workspaces from becoming unmanaged copies with longer retention than the source.

Verify Reconstruction and Failure Behavior

Before production and after material changes, test that you can:

1. follow one request from verified identity through gateway, policy decision, application action, and final outcome;
2. distinguish an authentication failure, authorization denial, upstream error, and successful business action;
3. detect a missing or malformed event instead of silently accepting a gap;
4. handle duplicate delivery without counting an action twice;
5. explain timestamps when hosts or regions have clock skew;
6. keep secrets and unnecessary payload data out of stored and displayed records;
7. detect unauthorized reads, exports, edits, retention changes, and deletions;
8. recover from collector, queue, network, and storage failures within the defined evidence-loss objective;
9. produce an approved investigation export and then dispose of it correctly.

Audit Design Checklist

• Which actions require audit evidence, and why?
• Which system is authoritative for actor, policy decision, business object, and outcome?
• Are identity and proxy headers trusted only after verification?
• Can events be joined without logging credentials or complete payloads?
• Are schema, policy, and configuration versions retained?
• Who can write, read, export, place a hold, or delete evidence?
• How are gaps, duplicates, delays, clock skew, and tampering detected?
• Is retention documented by data class and jurisdiction?
• Has a real investigation scenario been reconstructed end to end?

Summary

Gateway access logs become useful audit evidence only when their purpose, fields, trust sources, delivery, protection, retention, and review process are explicit. Record verified identity and policy context without copying sensitive traffic wholesale. Correlate the gateway's transport view with application outcomes, then test both reconstruction and failure behavior. That produces defensible evidence instead of a large, expensive collection of ambiguous log lines.

FAQ

Is an API gateway access log a complete audit trail?

No. It may prove that a request crossed the gateway, but the application usually owns the final business object and outcome. Correlate both sources.

Should audit logs contain request and response bodies?

Not by default. Record the minimum fields required for the audit purpose and add narrowly scoped, time-bounded capture only with legal, privacy, and security review.

Does immutable storage guarantee trustworthy audit evidence?

It can protect retained records from modification, but it cannot prove that every required event was generated or delivered. Monitor coverage and completeness separately.

Next Steps

Review the API gateway log storage architecture, then design fine-grained authorization evidence. For centrally governed gateway policy and operations, explore API7 Enterprise.