Audit Log API

View the audit trail of administrative and security events.

Base path: /api/admin/audit

List Audit Events

GET /api/admin/audit

Query parameters:

Parameter	Type	Description
limit	integer	Max results to return (default: 50, max: 500)
event	string	Filter by event_type
org	uuid	Filter by organization_id
user	uuid	Filter by user_id
since	ISO 8601	Filter events after this date

Response: 200 OK

{
  "data": [
    {
      "id": "event-uuid",
      "eventType": "organization.created",
      "eventCategory": "admin",
      "actorId": "user-uuid",
      "organizationId": "org-uuid",
      "userId": "user-uuid",
      "description": "Organization created",
      "metadata": {
        "name": "Acme Corp",
        "slug": "acme-corp"
      },
      "ipAddress": "192.168.1.1",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 156
}

Audit Event Types

Organization Events

Action	Description
organization.created	New organization created
organization.updated	Organization details updated
organization.suspended	Organization suspended
organization.activated	Organization reactivated
org.deleted	Organization deleted
organization.branding_updated	Branding settings changed

User Events

Action	Description
user.created	New user created
user.invited	Invitation created (no user record yet)
user.updated	User profile updated
user.deactivated	User deactivated
user.activated	User activated
user.deleted	User deleted
user.password_changed	Password changed
user.login_success	Successful login
user.login_failure	Failed login attempt

Client Events

Action	Description
client.created	New OIDC client created
client.updated	Client configuration updated
client.deleted	Client deleted
client.secret_generated	New client secret generated
client.secret_revoked	Client secret revoked

RBAC Events

Action	Description
role.created	New role created
role.updated	Role updated
role.deleted	Role deleted
permission.deleted	Permission deleted
role.permission_assigned	Permission assigned to role
role.permission_removed	Permission removed from role
user.role_assigned	Role assigned to user
user.role_removed	Role removed from user

Security Events

Action	Description
security.login_method_disabled	Attempted login via disabled method
security.2fa_enabled	2FA enabled for user
security.2fa_disabled	2FA disabled for user
security.rate_limited	Rate limit triggered

Data Export and Deletion Events

Action	Description
user.data_exported	User data exported (GDPR Article 20)
app.deleted	Application deleted
app.module.deleted	Application module deleted
claim.deleted	Claim definition deleted

Account Lockout Events

Action	Description
user.auto_locked	Account auto-locked after failed login threshold
user.auto_unlocked	Account auto-unlocked after cooldown expired

Audit durability

Compatibility audit events remain best-effort and do not change the public operation result. Authorized administrative mutations also write a required business audit row in the same PostgreSQL transaction as their database changes. Import is atomic: an audit failure rolls back the manifest and returns a minimal service-unavailable response. Bulk processing is intentionally per-item: an audit failure rolls back the current item, preserves earlier committed items, marks the current and remaining items not_attempted, and returns the ordered partial result with one correlation identifier.

Audit Retention & Cleanup

Porta supports configurable audit log retention with automatic cleanup of old entries.

Configure Retention

The retention period is managed via the audit_retention_days system configuration key:

# Set retention to 365 days
porta config set --key audit_retention_days --value 365

Cleanup Old Entries

DELETE /api/admin/audit/cleanup

Deletes audit log entries older than the configured audit_retention_days value.

Response: 200 OK

{
  "deleted": 1542,
  "retentionDays": 365,
  "cutoffDate": "2025-04-21T00:00:00.000Z"
}

WARNING

Audit cleanup is irreversible. Ensure your retention period meets your compliance requirements before running cleanup. Consider exporting old audit data to cold storage before purging.