Audit Logs

Implementation Status

The audit log schema and query capabilities are implemented. Comprehensive automatic audit logging of all user actions will be added in a future release.

The Manager maintains comprehensive audit logs of all significant actions performed in the system, providing accountability and compliance tracking.

Overview

Audit logs capture:

• User Actions - Create, update, delete operations on all entities
• Access Events - Login, logout, and access attempts
• Configuration Changes - Modifications to settings and configurations
• User Management - Role assignments and access grants
• System Events - Important system-level operations

Audit Log Structure

Each audit log entry contains:

• Entity Type - Type of resource (e.g., Project, Tenant, Application)
• Entity ID - Unique identifier of the affected resource
• Action - Operation performed (create, update, delete, etc.)
• Description - Human-readable description of the action
• Metadata - Additional context (JSON format)
• Changes - Before/after values for update operations
• User - User who performed the action
• IP Address - Source IP of the request
• User Agent - Client information
• Timestamp - When the action occurred
• Project - Project context (if applicable)

Viewing Audit Logs

Via UI

1. Navigate to Projects → Select project
2. Click Audit Logs tab
3. View chronological list with filters for entity type, action, user, and date range

Via API

Query audit logs using the GraphQL API:

auditLogs(projectID: ID!, filters: [Filter!], order: Order!, pagination: Pagination!)

Available fields: id, entityType, entityID, action, description, metadata, changes, ipAddress, userAgent, createdAt, user, project

Action Types

Audit logs track the following action types:

Resource Actions

• create - New resource created
• update - Existing resource modified
• delete - Resource removed
• view - Resource accessed (for sensitive operations)

Import/Export

• export - Data exported from system
• import - Data imported into system

Authentication

• login - User logged in
• logout - User logged out

Other

• other - Miscellaneous system events

Filtering Audit Logs

Use the filters parameter to narrow results:

By Entity Type:

filters: [{ field: "entity_type", value: "Application" }]

Common entity types: Project, Tenant, Application, Endpoint, Trigger, MachineUser, User2Project, User2Tenant, User2Application, Settings, BackendSettings, FrontendSettings

By Action:

filters: [{ field: "action", value: "delete" }]

By Date Range:

filters: [
  { field: "created_at", value: ">=2025-12-01T00:00:00Z" },
  { field: "created_at", value: "<=2025-12-31T23:59:59Z" }
]

By User:

filters: [{ field: "user_id", value: "user-uuid" }]

Understanding Changes

For update operations, the changes field contains before/after values:

{
  "changes": {
    "name": {
      "before": "Old Application Name",
      "after": "New Application Name"
    },
    "enabled": {
      "before": true,
      "after": false
    }
  }
}

This allows you to:

• Track configuration drift
• Identify who changed what and when
• Audit security-sensitive modifications
• Troubleshoot issues by reviewing history

Metadata Fields

The metadata field contains additional context specific to each action type:

Example - User Role Change:

{
  "metadata": {
    "role": "admin",
    "previous_role": "editor",
    "resource": "project-uuid"
  }
}

Example - Settings Update:

{
  "metadata": {
    "settings_type": "frontend",
    "modules_changed": ["theme", "locale"],
    "layer": "tenant"
  }
}

Use Cases

Compliance Auditing

Track access control changes to meet regulatory requirements. Filter by entity_type: "User2Application" or "User2Tenant" to audit permission changes.

Security Investigations

Investigate unauthorized access or suspicious activity by filtering for action: "delete" operations and reviewing ipAddress and userAgent fields.

Configuration Tracking

Monitor system configuration changes by filtering for entity_type: "Settings" with action: "update". Review the changes field for before/after values.

User Activity

Track actions by specific users using user_id filter. Useful for onboarding reviews, offboarding audits, or investigating specific incidents.

Best Practices

Regular Review

• Schedule audits - Review logs regularly (weekly/monthly)
• Monitor critical actions - Pay special attention to delete operations
• Track privilege escalation - Watch for role changes to admin
• Review access patterns - Identify unusual activity

Retention Policy

• Define retention periods - How long to keep logs
• Archive old logs - Export and store historical logs
• Compliance requirements - Meet regulatory retention needs
• Storage management - Balance detail with storage costs

Security Monitoring

• Alert on sensitive actions - Notify on critical operations
• Failed access attempts - Track authentication failures
• Privilege changes - Monitor role and permission changes
• Bulk operations - Investigate mass deletions or updates

Integration

• SIEM Integration - Export logs to security information systems
• Log Aggregation - Centralize logs from multiple projects
• Automated Analysis - Use tools to detect anomalies
• Reporting - Generate compliance and activity reports

Exporting Audit Logs

Export audit logs via the GraphQL API for archival or compliance:

• Use pagination (limit: 1000, offset: 0) to export large datasets
• Filter by date range for monthly/quarterly exports
• Export to JSON format for processing or storage
• Automate exports using cron jobs or scheduled tasks

Limitations

• Project Scope - Logs are project-scoped; query each project individually for cross-project analysis
• Project Creation - Some actions (like creating a project) occur before project context exists
• Pagination - Large result sets require pagination using offset and limit parameters

Troubleshooting

Missing Audit Logs:

• Action may not be logged (comprehensive logging still in development)
• Check project filter, date range, and pagination settings

Incorrect User Attribution:

• Verify action wasn't performed by machine user or system process
• Check user authentication was valid at action time

Cannot View Logs:

• Ensure user has Viewer role or higher
• Verify project ID and authentication token are valid

Privacy Considerations

Audit logs contain sensitive information:

• IP Addresses - Can identify user locations
• User Agents - Browser/client information
• Entity Data - May include sensitive configuration
• User Identity - Links actions to specific users

Privacy best practices:

• Access control - Limit who can view audit logs
• Data minimization - Log only what's necessary
• Anonymization - Consider anonymizing old logs
• Compliance - Follow GDPR/privacy regulations

API Reference

Complete audit log query documentation:

• Query Audit Logs
• Filter Options
• Pagination

See the full API Reference for details.