Audit logs

​

Overview

​

What gets logged

​

Properties

• Append-only. No update or delete operation exists on the audit_log table. The schema enforces this at the database level.
• Org-scoped. Every entry is stamped with org_id and the API only returns entries belonging to the requesting user’s organisation. Cross-tenant access is impossible by design.
• Admin-only. Reading audit logs requires the admin role.
• Best-effort write. The audit logger is designed to never raise — a failure to write a single audit entry never breaks the action being audited. Write failures are logged but not propagated.

​

Viewing audit logs

• Pagination — 50 entries per page by default, configurable up to 200
• Event filter — narrow to a single event code, e.g. login_failed
• User column — joined from the user table, so you see emails not UUIDs

​

API

# List audit logs (admin token required)
GET /api/v1/audit?limit=50&offset=0

# Filter by a specific event
GET /api/v1/audit?event=login_failed&limit=200

# Paginate
GET /api/v1/audit?limit=100&offset=100

{
  "data": {
    "logs": [
      {
        "id": "8fa1...",
        "event": "file_uploaded",
        "user_email": "alice@acme.com",
        "ip_address": "203.0.113.42",
        "created_at": "2026-04-07T09:14:22Z",
        "metadata": {
          "file_id": "...",
          "filename": "transactions_q1.csv",
          "size_bytes": 1485220
        }
      }
    ],
    "total": 18432
  }
}

​

Common queries

​

Retention

​

Tips

• Pull audit logs into your SIEM. The endpoint is paginated and stable; a small cron that polls ?event=login_failed and forwards to Splunk/Datadog gives you alerting without any custom integration.
• Audit before debugging. Before investigating a “weird state” complaint, pull event=* for the affected user’s email and look for a manual config change you forgot about.
• Pair with API keys. Every API key use creates an api_key_used event with the key prefix in metadata, so you can reconstruct exactly what an integration did.

​

What’s next?

• API keys — manage and rotate the keys whose usage shows up here
• Security overview — the broader compliance picture
• Data retention — control how long uploaded files are kept (separate from audit retention)