Audit Logs

Audit logging is off by default. When enabled, significant activity is recorded as structured audit.Event rows in audit_log. Security-critical transactional paths — registration, successful login session issuance, password change/reset, session creation/revocation, account deletion, and role changes — write the record in the same transaction as the state change, so the record exists if and only if that change committed. Standalone observations such as a failed login have no state transaction and are inserted directly. When at least one external sink is configured, the same write adds one audit_outbox obligation for the event; a background dispatcher claims it and fans it out to the configured sink set with retries. With no external sink configured there is no delivery machinery at all.

Configuration

goauth.WithAudit(goauth.AuditConfig{
    Enabled:       true,                    // optional, default false
    FailureMode:   audit.FailureOpen,   // optional, default fail-open — or audit.FailureClosed
    RetentionDays: 0,                       // optional, default 0 — keep forever (0 = forever)
    Workers:       3,                        // optional, default 3 — outbox dispatcher workers (only when Sinks set)
    BatchSize:     50,                       // optional, default 50 — outbox claim/delivery batch size
    FlushInterval: 100 * time.Millisecond,   // optional, default 100ms — outbox dispatch poll interval
    MaxAttempts:   10,                       // optional, default 10 — delivery attempts before a row is dead-lettered
    ClaimLease:    10 * time.Minute,         // optional, default 10m — floor 1m
    OutboxMaxAge:  7 * 24 * time.Hour,       // optional, default 7d — pending-row age bound (negative disables)
    DeadLetterTTL: 7 * 24 * time.Hour,       // optional, default 7d — dead-letter evidence window (negative keeps forever)
    OutboxMaxRows: 100000,                   // optional, default 100000 — backlog emergency valve (negative = unbounded)
    Sinks:         []audit.EventSink{myKafkaSink}, // optional, default none
    // EnqueueFailureMode resolves fail-open vs fail-closed per event (nil = fail-open everywhere)
})
goauth.WithAuditSink(myOtherSink) // optional — adds one more sink at a time

WithAuditSink appends one sink at a time without needing to repeat the whole config; calling WithAudit more than once doesn't duplicate sinks already added.

Startup rejects an unsafe or unbounded sink/lease combination and refuses to enable external delivery when audit_outbox is missing. Apply the schema migration before deploying this write path; goauth.New returns an error instead of starting with a delivery configuration it cannot honor. Finite audit retention also rejects negative (unbounded) outbox clocks.

Built-in webhook sink

For real-time delivery to an external service (a SIEM, alerting, or your own automation endpoint), the library ships a first-party webhook sink implementing the same audit.EventSink interface:

sink, err := audit.NewWebhookSink(audit.WebhookConfig{
    Endpoint: "https://ops.example.com/hooks/auth",
    Secret:   "shared-hmac-secret", // optional, recommended
    Timeout:  10 * time.Second,     // optional, default 10s
})
if err != nil { /* empty endpoint */ }
goauth.WithAuditSink(sink)

Each audit event is delivered as one HTTP POST with the JSON-serialized audit.Event body. When Secret is set, every request carries an X-Signature: sha256=<hex> header — the HMAC-SHA256 of the raw body — which the receiver should recompute and verify (constant-time compare) before trusting the payload; a discovered URL alone must not allow forged events.

Delivery is durable and at-least-once: the delivery obligation is written in the same transaction as the record, so a process crash after commit cannot lose it. The dispatcher retries failed deliveries with exponential backoff (10s base, capped at 1h) up to MaxAttempts, then marks the row dead-lettered — the row is retained for DeadLetterTTL as failure evidence, never deleted outright. Because delivery is at-least-once, receivers must deduplicate on the event's id (not on the HMAC signature, which proves authenticity, not uniqueness). Delivery is ordered critical-first, oldest-first within a tier; login.failed-family noise ships best-effort behind it, so a login flood cannot starve the discrete compromise signals. Delivery never touches audit_log: retries, dead-lettering, and backlog eviction change only the outbox.

At the receiver boundary, make the event id a unique inbox key and record it in the same transaction as the side effect triggered by the event. If that insert conflicts because the ID was already processed, skip the side effect and still return a successful 2xx response. This covers the live-lease race where the original request is still being processed when another dispatcher steals its expired claim; both deliveries may arrive, but the receiver applies the event once. Returning an error for a recognized duplicate causes needless retries and can eventually dead-letter an event that was already handled.

The database claim rechecks the retry deadline before incrementing the attempt count. A dispatcher that selected an event before another dispatcher scheduled backoff cannot claim it early or spend another attempt during that delay.

Consumer notes

Sinks are read once at startup: a sink added after records have already run (WithAuditSink on a live instance) gets no outbox rows for events recorded before it was registered — those events went to the sinks that existed then. Register every delivery sink before the first request.

The outbox tracks one obligation per event, not one row per sink. If an earlier sink succeeds and a later sink fails, retrying the obligation may redeliver the event to the earlier sink. This is another reason every receiver must make event-ID deduplication atomic with its side effect.

Frontend client setup

The Client examples below call the same apiRequest(baseUrl, method, path, body) helper used throughout these guides — see Client → Setup. The named-method wrapper for both endpoints on this page lives on Client → Admin.

What gets recorded

Every event carries a type, a severity (info / warning / error / critical), whether it successed, and — depending on the event — an actor, a target user, a session, an org, an IP, and a user agent. The full type list, grouped by area:

This list can grow across versions — treat event_type as an opaque string in your filters rather than an exhaustive enum you validate against.

With app permissions enabled, querying audit records requires goauth.app.audit.read or the protected administrator identity, with required MFA assurance. Supply ActorSessionID in direct administrative calls. Authorization changes record through the existing configured audit publisher inside their database transaction; the local permission CLI always uses database-only, fail-closed audit. Removing library definitions records their removed role links, and reinstalling never restores those links.

Events emitted before an account is resolved — failed/locked login, admin login failure, verification send, and password-reset request — leave actor_id null and put the submitted address in metadata.email. This keeps PostgreSQL's UUID-typed actor column valid while preserving the security signal.

Querying audit logs

List all audit logs — GET /admin/audit-logs

Query params (all optional)

Response (200 OK)

{
  "events": [
    {
      "id": "...",
      "type": "login.failed",
      "severity": "warning",
      "success": false,
      "actorId": null,
      "actorEmail": null,
      "targetUserId": null,
      "targetEmail": null,
      "sessionId": null,
      "orgId": null,
      "ip": "192.168.1.1",
      "userAgent": "Mozilla/5.0 ...",
      "requestId": "...",
      "metadata": {},
      "createdAt": "2026-08-09T12:00:00Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

The list response carries no total — fetch it from Count audit logs below.

actorEmail/targetEmail are resolved server-side from actorId/targetUserId for the returned page — not stored, and null if the corresponding *Id is null or that user no longer exists.

Errors

curl

curl "https://api.myapp.com/admin/audit-logs?event_type=login.failed&limit=50" \
  -H "Origin: https://myapp.com" \
  -b admin-cookies.txt

Programmatic (Go)

Go examples on this page import github.com/nazimdjebloun/go-auth/api for operation inputs and results.

result, err := auth.Services().Admin.ListAuditLogs(ctx, api.AdminListAuditLogsInput{
    ActorID:    adminID, // the admin making this call
    EventTypes: []string{"login.failed"},
    Limit:      50,
})
// result.Events

auth.Services().Admin.ListAuditLogs — not auth.Services().AuditLog.List directly — is the supported programmatic path: it resolves EventActorEmail/TargetEmail to IDs and enforces that the calling actor is an admin, like the other auth.Services().Admin methods.

Client

const { events } = await apiRequest(
  API_BASE, "GET", "/admin/audit-logs?event_type=login.failed&limit=50"
);

See Client → Audit logs for the wrapper, data table, and filters.

Count audit logs — GET /admin/audit-logs/count

The matching total for the list, split into its own call so a paginated log view doesn't run a COUNT(*) on every page. Takes every filter param of the list except offset/limit.

Response (200 OK): { "count": 1000 }

n, err := auth.Services().Admin.CountAuditLogs(ctx, api.AdminListAuditLogsInput{
    ActorID:    adminID,
    EventTypes: []string{"login.failed"},
})

const { count } = await apiRequest(API_BASE, "GET", "/admin/audit-logs/count?event_type=login.failed");

See Client → Audit logs for the wrapper.

GET /admin/users/{id}/audit-logs/count is the same, scoped to one user (see below).

List one user's audit logs — GET /admin/users/{id}/audit-logs

Identical query params and response shape to the endpoint above — this one just forces target_user_id to the {id} in the path, overriding anything passed in the query string for target_user_id/targetEmail. Its total lives at GET /admin/users/{id}/audit-logs/count.

curl

curl "https://api.myapp.com/admin/users/b3f1.../audit-logs?limit=50" \
  -H "Origin: https://myapp.com" \
  -b admin-cookies.txt

Programmatic (Go)

result, err := auth.Services().Admin.ListAuditLogs(ctx, api.AdminListAuditLogsInput{
    ActorID:      adminID,
    TargetUserID: &userID,
    Limit:        50,
})

Client

const { events } = await apiRequest(API_BASE, "GET", `/admin/users/${userId}/audit-logs`);
const { count } = await apiRequest(API_BASE, "GET", `/admin/users/${userId}/audit-logs/count`);

See Client → Audit logs for the wrapper and data table.

Next

• Admin — most of the actions that show up as admin.* events here
• Routes — full param reference