Skip to main content

​
Overview

ORCA writes an immutable audit log entry every time something security-relevant happens in your workspace — logins, file uploads, jobs, configuration changes, key rotations. Entries are append-only: there is no API or UI path that can delete or modify them after the fact. This is the system of record auditors and compliance teams ask about. It’s also the first place to look when something unexpected happens in your workspace and you need a clean answer to “who did what, when.”

​
What gets logged

Every entry stores the event code, the acting user (if any), the source IP, a timestamp, and a JSON metadata payload describing the action. The events ORCA always records:
CategoryEvents
Authenticationlogin, logout, login_failed, register, email_verified, 2fa_enabled, 2fa_disabled
Files & jobsfile_uploaded, file_rejected_raw_password, job_created, job_started, job_completed, files_deleted, files_expiring
Compliancegdpr_check_disabled, credits_added
API accessapi_key_created, api_key_revoked, api_key_used
The list is enforced in code — security-critical events cannot be silently dropped, and the project security rules explicitly forbid removing audit calls from any of the events above.

​
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

In the web app, open Settings → Audit logs (admin only). The viewer supports:
  • 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
Newest entries appear first.

​
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
Response shape: 
{
  "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
  }
}
limit is capped at 200 entries per request. Use offset to paginate through larger result sets.

​
Common queries

You want to knowFilter
Failed logins in the last dayevent=login_failed then sort by created_at
Who disabled GDPR scanning on a jobevent=gdpr_check_disabled
Whether a specific file ever existedevent=file_uploaded and search the metadata
Who created the API key with prefix ok_live_abcevent=api_key_created
When raw password files were rejectedevent=file_rejected_raw_password

​
Retention

Audit logs are retained for the lifetime of the organisation by default. They are not deleted by the data retention worker — that worker only handles uploaded customer files, not security records. If your compliance posture requires log archival to a customer-controlled bucket (e.g. for SIEM ingestion), contact support — we can configure scheduled exports to S3 or webhook delivery.

​
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)