Audit Logs

HelloJohn records a structured audit log for every security-relevant action across all tenants. Audit logs answer the question: who did what, when, and from where.

What is an audit log?

An audit log is an append-only, tamper-evident record of actions performed in the system. Each entry captures:

• Who — the actor (user ID, admin ID, API key ID, or system)
• What — the action taken (e.g., user.login, mfa.enrolled)
• When — precise timestamp in UTC
• Where — IP address, user agent, and geographic location
• Result — success or failure, with reason on failure
• Context — tenant ID, organization ID, and affected resource

Why audit logs matter

• Security investigations: Trace suspicious activity back to its source
• Compliance: Satisfy SOC 2, HIPAA, GDPR, and ISO 27001 audit requirements
• Debugging: Understand exactly what happened during an incident
• Accountability: Non-repudiation — users cannot deny actions they performed

Audit log entry structure

{
  "id": "evt_audit_01HXXXX",
  "type": "user.login",
  "actor": {
    "id": "usr_01HXXXX",
    "email": "alice@example.com",
    "type": "user"
  },
  "resource": {
    "id": "usr_01HXXXX",
    "type": "user"
  },
  "tenant_id": "tnt_01HXXXX",
  "organization_id": null,
  "ip_address": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "country": "US",
  "result": "success",
  "metadata": {
    "auth_method": "email_password",
    "mfa_used": true,
    "session_id": "sess_01HXXXX"
  },
  "created_at": "2024-01-15T14:23:05.123Z"
}

Availability

On self-hosted deployments, audit logs are stored in your own PostgreSQL database with no retention limits.

Accessing audit logs

Dashboard

Navigate to Settings → Audit Logs in the admin dashboard. Filter by date range, actor, event type, IP address, or result.

API

GET /v1/audit-logs
Authorization: Bearer <admin_api_key>

Query parameters:

# Get failed logins in the last 24 hours
curl "https://auth.yourdomain.com/v1/audit-logs?type=user.login&result=failure&from=2024-01-15T00:00:00Z" \
  -H "Authorization: Bearer <admin_api_key>"

Forwarding to a SIEM

HelloJohn can forward audit events to external SIEM systems in real time via webhooks:

# Register a webhook for all audit events
POST /v1/webhooks
{
  "url": "https://your-siem.com/ingest/hellojohn",
  "events": ["audit.*"],
  "secret": "hmac-signing-secret"
}

Supported SIEM integrations (Cloud Enterprise):

• Datadog — via Datadog Logs API
• Splunk — via HTTP Event Collector (HEC)
• AWS CloudWatch — via Kinesis Firehose
• Elastic — via Elasticsearch Bulk API
• Generic webhook — HMAC-signed JSON

Next steps