Audit API

Event history, access logs, and RBAC change tracking. Provides a centralized audit trail for all platform operations.

Overview

Audit events are generated for every significant platform operation: authentication attempts, RBAC changes, goal lifecycle events, provider configuration changes, and administrative actions. Events are stored in Mnesia with 30-day retention and compacted hourly.

Authentication

All endpoints require Authorization: Bearer <token> with admin role. Audit data is visible only to administrators.

Endpoints

List Audit Events

GET /api/v1/audit

Query parameters: type, user_id, resource, from, to, limit (default 50), offset.

Response:

{
  "ok": true,
  "data": [
    {
      "id": "aud-ev-001",
      "type": "auth.login",
      "user_id": "usr-abc123",
      "resource": "/api/v1/auth/token",
      "action": "login",
      "result": "success",
      "ip": "10.0.0.42",
      "timestamp": 1745600000
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Get Audit Event Details

GET /api/v1/audit/:id

Returns the full audit event with all metadata.

RBAC Change Log

GET /api/v1/audit/rbac

Filtered view of RBAC-specific changes: role assignments, permission updates, team membership changes.

{
  "ok": true,
  "data": [
    {
      "type": "rbac.role_assigned",
      "user_id": "usr-abc123",
      "role": "admin",
      "team": "ops",
      "changed_by": "usr-admin",
      "timestamp": 1745600000
    }
  ]
}

Access Logs

GET /api/v1/audit/access

Filtered view of HTTP request audit entries. Supports path, method, status_code filters.

Audit Event Types:

Event Type	Description
auth.login	Authentication attempt
auth.logout	Token invalidation
auth.failure	Failed authentication
rbac.role_assigned	Role assignment changed
rbac.permission_updated	Permission set modified
goal.created	Goal created
goal.cancelled	Goal cancelled
provider.created	Provider configuration added
provider.deleted	Provider configuration removed
infra.config_reload	Configuration reloaded

Error Codes:

Code	Description
401	Authentication required
403	Admin role required
404	Event not found

Examples:

curl http://127.0.0.1:11434/api/v1/audit?type=auth.login&limit=10 \
  -H "Authorization: Bearer $TOKEN"

curl http://127.0.0.1:11434/api/v1/audit/rbac \
  -H "Authorization: Bearer $TOKEN"