Audit Log Management

Arbitex Gateway records every request, policy decision, DLP finding, authentication event, and administrative action in a tamper-evident audit log. This guide covers how to view and filter logs, export records for compliance retention, verify the HMAC integrity chain, and connect your SIEM for real-time event streaming.

All audit log endpoints require the Org Admin role.

What gets logged

Every audit log entry captures:

Field	Description
`request_id`	Unique identifier for this log entry
`timestamp`	ISO 8601 UTC timestamp
`action`	Event type (see Action types)
`user_id`	UUID of the user who triggered the event
`model`	Model identifier (e.g., `claude-sonnet-4-20250514`)
`provider`	Provider name (e.g., `anthropic`)
`outcome`	Policy engine decision: `ALLOW`, `BLOCK`, `REDACT`, `REQUIRE_APPROVAL`
`dlp_findings`	Array of DLP detections (type, tier, confidence, location)
`policy_rules_matched`	Names of policy rules that matched
`credint_hit`	Whether a credential matched the breach corpus
`routing_mode`	How the request was routed (`Single`, `Fallback`, `Balanced`)
`prompt_tokens`	Input token count
`completion_tokens`	Output token count
`latency_ms`	End-to-end gateway latency
`hmac`	HMAC-SHA256 signature of this entry
`previous_hmac`	Signature of the preceding entry (chain link)

The hmac and previous_hmac fields form an unbroken chain. Any tampering, deletion, or reordering of entries is detectable by walking the chain.

Action types

Action	Trigger
`chat_completion`	Normal model request
`dlp_block`	Request blocked by DLP finding
`dlp_redact`	Request content was redacted
`policy_block`	Request blocked by policy rule
`policy_approval_requested`	Request held for human review
`policy_approval_approved`	Human reviewer approved a held request
`policy_approval_denied`	Human reviewer denied a held request
`auth_success`	Successful API key authentication
`auth_failure`	Failed authentication attempt
`admin_login`	Admin portal sign-in
`key_created`	API key created
`key_rotated`	API key rotated
`key_deleted`	API key deleted
`rule_created`	DLP or policy rule created
`rule_updated`	DLP or policy rule updated
`rule_deleted`	DLP or policy rule deleted
`siem_config_created`	SIEM connector configured
`provider_created`	Provider credential added

Viewing and filtering logs

Search endpoint

GET /api/admin/audit-logs/
Authorization: Bearer arb_live_your-api-key-here

All filter parameters are optional and ANDed together:

Parameter	Type	Description
`limit`	integer (1–500, default 50)	Results per page
`offset`	integer (default 0)	Pagination offset
`action`	string	Exact action type (e.g., `dlp_block`)
`user_id`	string (UUID)	Filter by user
`model_id`	string	Filter by model (e.g., `claude-sonnet-4-6`)
`provider`	string	Filter by provider (e.g., `anthropic`)
`created_after`	ISO 8601	Lower bound on `created_at` (inclusive)
`created_before`	ISO 8601	Upper bound on `created_at` (inclusive)
`search`	string	Substring search on prompt and response text
`outcome`	string	Filter by policy outcome (`ALLOW`, `BLOCK`, `REDACT`)

List recent entries

curl "https://gateway.arbitex.ai/api/admin/audit-logs/?limit=20" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

{
  "entries": [
    {
      "request_id": "req_01HZ8X9K2P3QR4ST5UV6WX7YZ",
      "timestamp": "2026-03-12T14:32:01.847Z",
      "action": "chat_completion",
      "user_id": "usr_alice_johnson",
      "model": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "outcome": "ALLOW",
      "dlp_findings": [],
      "policy_rules_matched": [],
      "credint_hit": false,
      "routing_mode": "Single",
      "prompt_tokens": 28,
      "completion_tokens": 42,
      "latency_ms": 387
    }
  ],
  "total": 14823,
  "limit": 20,
  "offset": 0
}

Filter by blocked requests in a date range

curl "https://gateway.arbitex.ai/api/admin/audit-logs/?outcome=BLOCK&created_after=2026-03-01T00:00:00Z&created_before=2026-03-11T23:59:59Z&limit=100" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

Find all DLP events for a user

curl "https://gateway.arbitex.ai/api/admin/audit-logs/?action=dlp_block&user_id=usr_alice_johnson&limit=50" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

Look up a specific request

Use the X-Arbitex-Request-Id response header from any gateway call to find the exact audit entry:

REQUEST_ID="req_01HZ8X9K2P3QR4ST5UV6WX7YZ"
curl "https://gateway.arbitex.ai/api/admin/audit-logs/?request_id=$REQUEST_ID" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

Exporting logs

Export a signed package

Use the export endpoint to download a signed audit log archive for compliance retention, offline analysis, or handoff to regulators:

curl -X POST "https://gateway.arbitex.ai/api/admin/audit-logs/export" \
  -H "Authorization: Bearer $ARBITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "created_after": "2026-03-01T00:00:00Z",
    "created_before": "2026-03-11T23:59:59Z",
    "format": "jsonl"
  }'

{
  "export_id": "exp_01HZ...",
  "status": "processing",
  "record_count": null,
  "download_url": null,
  "expires_at": null
}

Export jobs are asynchronous. Poll for completion:

EXPORT_ID="exp_01HZ..."
curl "https://gateway.arbitex.ai/api/admin/audit-logs/export/$EXPORT_ID" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

{
  "export_id": "exp_01HZ...",
  "status": "complete",
  "record_count": 4823,
  "format": "jsonl",
  "download_url": "https://exports.arbitex.ai/signed/exp_01HZ....jsonl?token=...",
  "signature": "sha256=a3f2c1...",
  "expires_at": "2026-03-14T14:00:00Z"
}

The download_url is a pre-signed URL valid for 48 hours. The signature is an HMAC-SHA256 over the export file contents — verify it before ingesting the data.

Streaming export for large date ranges

For very large exports (millions of entries), use streaming export with chunked transfer:

curl -X POST "https://gateway.arbitex.ai/api/admin/audit-logs/export/stream" \
  -H "Authorization: Bearer $ARBITEX_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "created_after": "2026-01-01T00:00:00Z",
    "created_before": "2026-03-31T23:59:59Z",
    "format": "jsonl"
  }' \
  > audit-q1-2026.jsonl

Streaming exports write one JSON object per line as records are read from the database. No intermediate storage is required on the server side.

Export formats

Format	Description	Best for
`jsonl`	One JSON object per line	Log pipelines, SIEM ingestion, programmatic processing
`csv`	Comma-separated, headers on first row	Spreadsheet analysis, reporting
`ndjson`	Identical to `jsonl`	Compatibility alias

Verifying HMAC chain integrity

Every audit entry contains an hmac field (HMAC-SHA256 over the entry’s data) and a previous_hmac field (the hmac of the preceding entry). This forms a linked chain — deleting, modifying, or reordering any entry breaks the chain.

Verify via API

Trigger a full chain verification on demand:

curl -X POST "https://gateway.arbitex.ai/api/admin/audit-logs/verify" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

{
  "valid": true,
  "entries_checked": 14823,
  "errors": []
}

If tampering is detected:

{
  "valid": false,
  "entries_checked": 14823,
  "errors": [
    {
      "entry_id": "req_01HZ...",
      "position": 4201,
      "error": "HMAC mismatch: computed a3f2c1... expected b7e9d4..."
    }
  ]
}

The position field identifies which entry in the chain is broken. Check errors for the exact entry IDs and error descriptions.

Verify an exported package

To verify the integrity of an export file before ingesting it:

import hashlib
import hmac
import json

HMAC_KEY = b"your-audit-hmac-key"

def verify_export(filepath: str) -> bool:
    with open(filepath) as f:
        entries = [json.loads(line) for line in f]

    previous_hmac = None
    for i, entry in enumerate(entries):
        # Reconstruct the HMAC (exclude hmac and previous_hmac fields)
        data = {k: v for k, v in entry.items() if k not in ("hmac", "previous_hmac")}
        if previous_hmac is not None:
            data["previous_hmac"] = previous_hmac

        expected = hmac.new(
            HMAC_KEY,
            json.dumps(data, sort_keys=True).encode(),
            hashlib.sha256,
        ).hexdigest()

        if entry["hmac"] != expected:
            print(f"Chain broken at entry {i}: {entry['request_id']}")
            return False

        previous_hmac = entry["hmac"]

    print(f"Chain verified: {len(entries)} entries intact")
    return True

verify_export("audit-q1-2026.jsonl")

The AUDIT_HMAC_KEY is configured by your platform admin in the gateway environment variables. Contact your admin if you need the verification key.

SIEM integration

Connect a SIEM to receive audit events in real time via push connector. Events are forwarded as they are generated — no polling required.

Supported SIEM connectors

Connector	`connector_type` value
Splunk HTTP Event Collector	`splunk_hec`
Microsoft Sentinel (Log Analytics)	`sentinel`
Elastic (Elasticsearch / ESQL)	`elastic`
Datadog Log Management	`datadog`
Sumo Logic	`sumo_logic`
Palo Alto Cortex XSIAM	`cortex_xsiam`
IBM QRadar	`qradar`

Splunk HEC setup

1. In Splunk: Create an HTTP Event Collector token under Settings > Data Inputs > HTTP Event Collector. Note the HEC endpoint URL and token.

2. In Arbitex: Create the SIEM connector config:

curl -X POST "https://gateway.arbitex.ai/v1/org/siem-configs" \
  -H "Authorization: Bearer $ARBITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connector_type": "splunk_hec",
    "name": "Splunk Production",
    "config": {
      "hec_url": "https://splunk.example.com:8088/services/collector/event",
      "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "index": "arbitex_audit",
      "source": "arbitex_gateway",
      "sourcetype": "arbitex:audit"
    },
    "enabled": true
  }'

3. Test the connection:

SIEM_CONFIG_ID="siem_01HZ..."
curl -X POST "https://gateway.arbitex.ai/v1/org/siem-configs/$SIEM_CONFIG_ID/test" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

{
  "success": true,
  "latency_ms": 42,
  "message": "Test event delivered successfully"
}

Microsoft Sentinel setup

1. In Azure: Navigate to your Log Analytics workspace. Under Agents management, note the Workspace ID and Primary Key.

2. In Arbitex:

curl -X POST "https://gateway.arbitex.ai/v1/org/siem-configs" \
  -H "Authorization: Bearer $ARBITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connector_type": "sentinel",
    "name": "Azure Sentinel Production",
    "config": {
      "workspace_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "primary_key": "base64encodedprimarykey==",
      "log_type": "ArbitexAuditLog"
    },
    "enabled": true
  }'

Arbitex uses the Log Analytics Data Collector API to POST events. Events appear in Sentinel under the ArbitexAuditLog_CL custom log table within 5–10 minutes.

3. Sentinel KQL query to find blocked requests:

ArbitexAuditLog_CL
| where outcome_s == "BLOCK"
| where TimeGenerated > ago(24h)
| project TimeGenerated, user_id_s, action_s, dlp_findings_s, policy_rules_matched_s
| order by TimeGenerated desc

Elastic setup

1. In Elasticsearch: Create an API key with index permissions on the target index pattern (arbitex-*):

curl -X POST "https://elastic.example.com:9200/_security/api_key" \
  -H "Content-Type: application/json" \
  -u elastic:password \
  -d '{
    "name": "arbitex-ingest",
    "role_descriptors": {
      "arbitex-writer": {
        "cluster": ["monitor"],
        "indices": [{"names": ["arbitex-*"], "privileges": ["create_index", "index", "create"]}]
      }
    }
  }'

2. In Arbitex:

curl -X POST "https://gateway.arbitex.ai/v1/org/siem-configs" \
  -H "Authorization: Bearer $ARBITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connector_type": "elastic",
    "name": "Elastic Production",
    "config": {
      "url": "https://elastic.example.com:9200",
      "api_key": "base64encodedapikey==",
      "index": "arbitex-audit"
    },
    "enabled": true
  }'

Events are indexed as documents in arbitex-audit-{YYYY.MM.DD} using daily index rotation.

Viewing connector health

curl "https://gateway.arbitex.ai/v1/org/siem-configs" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

{
  "configs": [
    {
      "id": "siem_01HZ...",
      "connector_type": "splunk_hec",
      "name": "Splunk Production",
      "enabled": true,
      "last_delivery_at": "2026-03-12T14:35:00Z",
      "last_delivery_status": "success",
      "error_count_24h": 0
    }
  ]
}

last_delivery_status shows the outcome of the most recent event delivery. error_count_24h shows delivery failures in the past 24 hours. If this is non-zero, check the connector configuration and test the connection.

For platform-level connector health across all organizations, see SIEM Admin API.

Compliance use cases

SOC 2 — Access and change management evidence

Export all admin_login, key_created, key_rotated, rule_created, and rule_updated events for a period and retain them for 12 months:

curl -X POST "https://gateway.arbitex.ai/api/admin/audit-logs/export" \
  -H "Authorization: Bearer $ARBITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action_types": ["admin_login", "key_created", "key_rotated", "rule_created", "rule_updated"],
    "created_after": "2026-01-01T00:00:00Z",
    "created_before": "2026-12-31T23:59:59Z",
    "format": "jsonl"
  }'

HIPAA — Access log for PHI-adjacent requests

Filter for requests that triggered NER findings of type MEDICAL_RECORD or NPI:

curl "https://gateway.arbitex.ai/api/admin/audit-logs/?dlp_finding_type=MEDICAL_RECORD,NPI&limit=500" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

PCI-DSS — Cardholder data access

Filter for CREDIT_CARD findings and export quarterly:

curl -X POST "https://gateway.arbitex.ai/api/admin/audit-logs/export" \
  -H "Authorization: Bearer $ARBITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dlp_finding_types": ["CREDIT_CARD"],
    "created_after": "2026-01-01T00:00:00Z",
    "created_before": "2026-03-31T23:59:59Z",
    "format": "jsonl"
  }'

Reference

Resource	Link
Audit Event API (search, filter, pagination)	Audit Event API
Audit Log Export (signed packages, streaming)	Audit Log Export
SIEM Admin API (connector registry)	SIEM Admin API
SIEM Integration Guide	SIEM Integration Guide
Data Retention configuration	Data Retention
Alert configuration	Alert Configuration