Audit Log Format

AIP generates immutable audit logs in JSONL (JSON Lines) format. Each line is a complete JSON object representing a single authorization decision or identity event.

File Format

Format: JSONL (JSON Lines) - one JSON object per line Default location: aip-audit.jsonl (configurable) Characteristics:

Append-only (immutable)
One event per line
Parseable by jq, grep, log aggregation tools
Timestamp-ordered

Example log file:

{"timestamp":"2026-01-24T10:30:45.123Z","direction":"upstream","method":"tools/call","tool":"read_file","decision":"ALLOW","policy_mode":"enforce","violation":false}
{"timestamp":"2026-01-24T10:30:46.234Z","direction":"upstream","method":"tools/call","tool":"delete_file","decision":"BLOCK","policy_mode":"enforce","violation":true,"failed_arg":"path"}
{"timestamp":"2026-01-24T10:35:00.000Z","event":"TOKEN_ISSUED","session_id":"550e8400-e29b-41d4-a716-446655440000","token_id":"abc123def456"}

Authorization Decision Events

Logged for every tools/call request and JSON-RPC method invocation.

Required Fields

timestamp

string

required

ISO 8601 timestamp with millisecond precision.Format: YYYY-MM-DDTHH:MM:SS.sssZ (UTC)Example: "2026-01-24T10:30:45.123Z"

direction

string

required

Request direction.

Value	Description
`upstream`	Client → MCP server (request)
`downstream`	MCP server → Client (response)

decision

string

required

Authorization decision result.

Value	Description
`ALLOW`	Request permitted
`BLOCK`	Request denied
`ALLOW_MONITOR`	Would block, but allowed (monitor mode)
`RATE_LIMITED`	Blocked due to rate limit
`ASK_APPROVED`	User approved prompt
`ASK_DENIED`	User rejected prompt

policy_mode

string

required

Policy enforcement mode at decision time.

Value	Description
`enforce`	Violations are blocked
`monitor`	Violations logged but allowed

violation

boolean

required

Whether a policy violation was detected.Example: true if tool not in allowed_tools, even if mode: monitor allowed it through.

Optional Fields

method

string

JSON-RPC method name (e.g., "tools/call", "tools/list", "initialize").

tool

string

Tool name for tools/call requests.Example: "github_get_repo"

args

object

Tool arguments. Should be redacted for sensitive data.Security note: Consider omitting or redacting this field in production.

failed_arg

string

Name of argument that failed validation (if applicable).Example: "path"

failed_rule

string

Regex pattern that failed to match (if applicable).Example: "^/home/.*"

session_id

string

v1alpha2 feature. Session UUID when identity is enabled.Format: UUID v4Example: "550e8400-e29b-41d4-a716-446655440000"

token_id

string

v1alpha2 feature. Token nonce for correlation with identity events.Example: "abc123def456"

policy_hash

string

v1alpha2 feature. SHA-256 hash of policy at decision time.Format: 64-character hex stringExample: "a3c7f2e8d9b4f1e2c8a7d6f3e9b2c4f1a8e7d3c2b5f4e9a7c3d8f2b6e1a9c4f7"

Example Authorization Events

{
  "timestamp": "2026-01-24T10:30:45.123Z",
  "direction": "upstream",
  "method": "tools/call",
  "tool": "read_file",
  "args": {"path": "/home/user/data.txt"},
  "decision": "ALLOW",
  "policy_mode": "enforce",
  "violation": false,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "policy_hash": "a3c7f2e8d9b4f1e2c8a7d6f3e9b2c4f1a8e7d3c2b5f4e9a7c3d8f2b6e1a9c4f7"
}

Identity Events (v1alpha2)

Logged when identity.enabled: true. These events track token lifecycle and validation failures.

TOKEN_ISSUED

Logged when a new identity token is created.

event

string

required

Event type: "TOKEN_ISSUED"

timestamp

string

required

ISO 8601 timestamp.

session_id

string

required

Session UUID.

token_id

string

required

Token nonce.

expires_at

string

required

ISO 8601 expiration timestamp.

policy_hash

string

required

Policy hash at issuance time.

Example:

{
  "timestamp": "2026-01-24T10:30:00.000Z",
  "event": "TOKEN_ISSUED",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "token_id": "abc123def456",
  "expires_at": "2026-01-24T10:35:00.000Z",
  "policy_hash": "a3c7f2e8d9b4f1e2c8a7d6f3e9b2c4f1a8e7d3c2b5f4e9a7c3d8f2b6e1a9c4f7"
}

TOKEN_ROTATED

Logged when a token is rotated before expiry.

event

string

required

Event type: "TOKEN_ROTATED"

old_token_id

string

required

Previous token nonce.

new_token_id

string

required

New token nonce.

Example:

{
  "timestamp": "2026-01-24T10:34:00.000Z",
  "event": "TOKEN_ROTATED",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "old_token_id": "abc123def456",
  "new_token_id": "xyz789ghi012",
  "expires_at": "2026-01-24T10:39:00.000Z"
}

TOKEN_VALIDATION_FAILED

Logged when token validation fails.

event

string

required

Event type: "TOKEN_VALIDATION_FAILED"

error

string

required

Validation error reason (see Error Codes).Possible values:

token_expired
policy_changed
session_mismatch
binding_mismatch
replay_detected
audience_mismatch
malformed

Example:

{
  "timestamp": "2026-01-24T10:36:00.000Z",
  "event": "TOKEN_VALIDATION_FAILED",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "token_id": "abc123def456",
  "error": "token_expired"
}

REVOCATION

Logged when a token or session is revoked via the /v1/revoke endpoint.

event

string

required

Event type: "REVOCATION"

type

string

required

Revocation type: "session" or "token"

target

string

required

Session ID or token nonce that was revoked.

reason

string

Human-readable reason for revocation.

admin

string

Administrator who initiated revocation.

Example:

{
  "timestamp": "2026-01-24T10:30:00.000Z",
  "event": "REVOCATION",
  "type": "session",
  "target": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "Suspected compromise",
  "admin": "[email protected]"
}

DLP Events

Logged when DLP patterns match in requests or responses.

DLP_MATCH (Response)

event

string

required

Event type: "DLP_MATCH"

direction

string

required

"downstream" for response matches.

tool

string

required

Tool that returned sensitive data.

dlp_rule

string

required

Name of the DLP pattern that matched.

redacted

boolean

required

Whether content was redacted.

Example:

{
  "timestamp": "2026-01-24T10:30:50.567Z",
  "event": "DLP_MATCH",
  "direction": "downstream",
  "tool": "read_file",
  "dlp_rule": "AWS Key",
  "redacted": true
}

DLP_REQUEST_REDACTION (v1alpha2)

Logged when DLP redacts content in a request.

event

string

required

Event type: "DLP_REQUEST_REDACTION"

forwarded

boolean

required

Whether the redacted request was forwarded to the MCP server.

failure_reason

string

If not forwarded, why redaction failed.

Example:

{
  "timestamp": "2026-01-24T10:30:45.123Z",
  "event": "DLP_REQUEST_REDACTION",
  "tool": "http_request",
  "dlp_rule": "API Key",
  "redaction_count": 1,
  "forwarded": false,
  "failure_reason": "argument_validation_failed"
}

Querying Audit Logs

Using `jq`

Find all blocked requests:

cat aip-audit.jsonl | jq 'select(.decision == "BLOCK")'

Find violations in monitor mode:

cat aip-audit.jsonl | jq 'select(.violation == true and .policy_mode == "monitor")'

Count decisions by type:

cat aip-audit.jsonl | jq -r '.decision' | sort | uniq -c

Find all token validation failures:

cat aip-audit.jsonl | jq 'select(.event == "TOKEN_VALIDATION_FAILED")'

Track a specific session:

cat aip-audit.jsonl | jq 'select(.session_id == "550e8400-e29b-41d4-a716-446655440000")'

Using `grep`

Find DLP matches:

grep '"event":"DLP_MATCH"' aip-audit.jsonl

Find rate limited requests:

grep '"decision":"RATE_LIMITED"' aip-audit.jsonl

Log Aggregation

AIP audit logs are compatible with:

ELK Stack (Elasticsearch, Logstash, Kibana)
Splunk
DataDog
Grafana Loki
CloudWatch Logs

Example Logstash config:

input {
  file {
    path => "/var/log/aip-audit.jsonl"
    codec => "json"
  }
}

filter {
  date {
    match => ["timestamp", "ISO8601"]
  }
}

output {
  elasticsearch {
    hosts => ["localhost:9200"]
    index => "aip-audit-%{+YYYY.MM.dd}"
  }
}

Compliance and Retention

Immutability

Audit logs are append-only. Implementations must:

Never modify or delete existing log entries
Use atomic append operations
Protect log files with read-only permissions after writing

Retention Policies

Recommended retention periods:

Use Case	Retention	Rationale
Development	7 days	Short-term debugging
Production	90 days	Security incident response
Compliance (SOC 2)	1 year	Audit requirements
Compliance (HIPAA)	6 years	Legal requirements

Sensitive Data

Best practices:

Redact args field in production logs
Encrypt log files at rest (e.g., LUKS, AWS KMS)
Restrict log file access to security team only
Use separate log sinks for high-sensitivity environments

Example: Redact arguments:

{
  "tool": "postgres_query",
  "args": "[REDACTED]",
  "decision": "ALLOW"
}

Next Steps

Policy YAML

Configure audit log behavior in policy

Error Codes

Understand decision results

Token Format

Identity token structure reference

Monitoring

Set up log aggregation and alerting

Specifications

API Reference

SDKs & Implementations

File Format

Authorization Decision Events

Required Fields

Optional Fields

Example Authorization Events

Identity Events (v1alpha2)

TOKEN_ISSUED

TOKEN_ROTATED

TOKEN_VALIDATION_FAILED

REVOCATION

DLP Events

DLP_MATCH (Response)

DLP_REQUEST_REDACTION (v1alpha2)

Querying Audit Logs

Using `jq`

Using `grep`

Log Aggregation

Compliance and Retention

Immutability

Retention Policies

Sensitive Data

Next Steps

Policy YAML

Error Codes

Token Format

Monitoring

Build docs developers (and LLMs) love

Specifications

API Reference

SDKs & Implementations

​File Format

​Authorization Decision Events

​Required Fields

​Optional Fields

​Example Authorization Events

​Identity Events (v1alpha2)

​TOKEN_ISSUED

​TOKEN_ROTATED

​TOKEN_VALIDATION_FAILED

​REVOCATION

​DLP Events

​DLP_MATCH (Response)

​DLP_REQUEST_REDACTION (v1alpha2)

​Querying Audit Logs

​Using jq

​Using grep

​Log Aggregation

​Compliance and Retention

​Immutability

​Retention Policies

​Sensitive Data

​Next Steps

Policy YAML

Error Codes

Token Format

Monitoring

Build docs developers (and LLMs) love

File Format

Authorization Decision Events

Required Fields

Optional Fields

Example Authorization Events

Identity Events (v1alpha2)

TOKEN_ISSUED

TOKEN_ROTATED

TOKEN_VALIDATION_FAILED

REVOCATION

DLP Events

DLP_MATCH (Response)

DLP_REQUEST_REDACTION (v1alpha2)

Querying Audit Logs

Using `jq`

Using `grep`

Log Aggregation

Compliance and Retention

Immutability

Retention Policies

Sensitive Data

Next Steps