Audit Logs

Nothing writes to the audit log yet

The audit log schema and the auditLogs query are implemented, but no code in the Manager ever creates an AuditLog row — the table stays empty, so the query always returns nothing. Do not rely on it for accountability or compliance today. See Known Issues.

The one exception is the ESB audit log, a separate table that is written on ESB requests according to each endpoint's logLevel — see ESB.

The Manager is intended to record significant actions performed in the system, providing accountability and compliance tracking. This page documents the schema and query interface that exist today, and the events that are planned to populate them.

Overview

Audit logs are intended to 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

None of these are emitted yet.

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. Open the Audit Logs page
3. View the chronological list with a text search and filters for action and entity type; click an entry to see its full details

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: "entityType", value: "Application" }]

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

By Action:

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

Only three filter fields exist

The resolver honours entityType, action, and description only. A Filter is {field, value} with no operator support, so date-range and user filters are not available, and an unrecognised field (including the snake_case entity_type) is silently ignored rather than rejected — the query returns unfiltered results.

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": "owner",
    "previous_role": "developer",
    "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 entityType: "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 entityType: "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 owner or administrator
• 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 you are a member of the project
• Verify the 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.