Audit Logs

Audit logs record resource operations across the system: the actor, action, resource, before/after change snapshots, and source IP. Sensitive fields are redacted at write and display time, so raw secrets never appear in logs. Viewing audit logs requires audit:read; exporting requires audit:export.

Audit Log Events

Audit logs cover the following event types. Each event records the actor, timestamp, resource, operation type, status, and change details.

Authentication Events

User login, logout, and registration actions:

User Management Events

Administrator actions on user accounts:

Team Management Events

Team creation and member changes:

Agent Events

Agent creation, update, publish, and deletion:

API Key Events

API Key creation and state changes:

System Settings Events

Site configuration changes:

Security Events

Account security-related operations:

Viewing and Filtering

Open Admin > Audit Logs. Each entry shows: timestamp, user, action, resource type, resource name, operation (create/read/update/delete), status, IP address, and details.

Search and Filtering

The list endpoint GET /api/v1/admin/audit-logs supports the following query parameters:

Viewing Log Details

Click a log entry to view full details, including:

• Basic Information: ID, timestamp, user, user ID, action, status
• Resource Information: Resource type, resource ID, resource name, operation type
• Request Information: IP address, User Agent, auth method
• Changes: before / after field-level change snapshots (sensitive values redacted)
• Metadata: Team ID/name, model, duration, etc.

Sensitive Data Redaction

Field-level before / after change data is processed by AuditLogService.sanitize_changes before storage:

• Sensitive fields are masked: Keys containing password, hashed_password, api_key, secret_key, access_token, refresh_token, private_key, secret, or token are masked. String values longer than 8 characters show only the first 8 characters followed by ***; other values are replaced with ***.
• Email addresses are partially masked: with a local part longer than 2 characters the first and last characters are kept (a***e@example.com); with 2 or fewer, only the first is kept (a***@example.com).
• Nested dictionaries are processed recursively.
• Values are truncated to a maximum field length (500 characters); oversized structures are replaced with a preview string.

Because redaction happens at write time, raw secrets never appear in audit logs.

Exporting Audit Logs

Export Formats

Supports CSV and JSON. The export endpoint GET /api/v1/admin/audit-logs/export?format=csv|json accepts every list filter except resource_id (user_id, team_id, action, resource_type, status, start_date, end_date, search) and returns up to 10,000 logs, newest first.

CSV columns: ID, Time, User, Action, Resource Type, Resource Name, Operation, Status, IP Address, Error Message

JSON: Exports full serialized entries (including changes).

curl -X GET "https://your-domain.com/api/v1/admin/audit-logs/export?format=csv" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Retention and Archival

Retention Policy

Retention is controlled by the audit_log_retention_days site setting, default 365 days with a range of 30-3650.

Configuration: Navigate to Admin > Site Settings > Storage, set Audit log retention (days) and Archive file storage path (default /var/log/clouisle/audit_archives).

Manual Archive

1. Navigate to Admin > Site Settings > Storage.
2. In the Audit Logs section, click Archive and confirm.
3. The task runs asynchronously (requires audit:export); the UI polls task status every 2 seconds and times out after 5 minutes.

Note: The manual archive control lives on the Storage settings page, not on the audit log page — the audit log page only views, filters, and exports.

Endpoints used:

All three require audit:export; both success and failure of the trigger are themselves written to the audit log (trigger_audit_log_archive).

How Archiving Works:

• The archive task tasks.archive_old_audit_logs selects logs older than the retention cutoff (now - audit_log_retention_days)
• Logs are exported to local JSON files grouped by month, e.g. /var/log/clouisle/audit_archives/audit_logs_202602.json (existing monthly files are appended to)
• Once archived, those rows are deleted from the database

Archive Status Query

GET /api/v1/admin/audit-logs/stats/retention returns: configured retention_days, cutoff_date, logs_to_archive, oldest_log_date, and next_archive_date.

Statistics Endpoints

GET /api/v1/admin/audit-logs/stats returns aggregate statistics: total logs, today's logs, failed logs, active users (last 7 days), top 5 actions, top 5 users.

API Endpoint Reference

Best Practices

Audit Logging

• Enable audit logging for all actions
• Log both successes and failures
• Include sufficient context
• Protect log integrity
• Review logs regularly
• Archive logs appropriately
• Monitor for anomalies
• Set up alerts for critical events

Log Analysis

• Review logs regularly
• Look for patterns and trends
• Investigate anomalies
• Generate regular reports
• Share findings with team
• Document incidents and remediation
• Use logs for compliance

Security

• Restrict log access
• Encrypt archived logs
• Use secure storage
• Monitor log access behavior
• Audit the auditors
• Maintain log integrity
• Comply with regulations

See also:

• Roles & Permissions — audit:read / audit:export permissions
• Notifications — security event notification channels