Audit Log API

Query system audit trail and security events

All audit log endpoints require admin role. Unauthorized users will receive a 403 Forbidden response.

Overview

The Audit Log API provides access to Mission Control’s comprehensive security and activity audit trail. All administrative actions, configuration changes, and system events are automatically logged with actor information, timestamps, and contextual details.

Audit events are retained based on the retention.audit_log_days setting (default: 180 days).

Query Audit Log

Search and filter audit events with flexible query parameters.

cURL

curl -X GET "https://your-domain.com/api/audit?action=settings_update&limit=100" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

Query Parameters

action · string

Filter by action type (e.g., settings_update, backup_create, user_created)

actor · string

Filter by actor username (e.g., admin, scheduler)

limit · integer · default: "1000"

Maximum number of events to return (max: 10000)

offset · integer · default: "0"

Number of events to skip for pagination

since · integer

Unix timestamp - only return events created after this time

until · integer

Unix timestamp - only return events created before this time

Response

events · array · required

Array of audit event objects sorted by creation time (newest first)

id · integer · required

Unique event identifier

action · string · required

Action type (see Event Types section)

actor · string · required

Username of the user or system process that performed the action

actor_id · integer

User ID of the actor (null for system actors)

detail · object

Action-specific contextual data (parsed from JSON)

ip_address · string

IP address of the actor (for user actions)

created_at · integer · required

Unix timestamp of event creation

total · integer · required

Total count of events matching the query (before pagination)

limit · integer · required

Limit value used in the query

offset · integer · required

Offset value used in the query

Example Response

{
  "events": [
    {
      "id": 1523,
      "action": "settings_update",
      "actor": "admin",
      "actor_id": 1,
      "detail": {
        "updated_keys": ["retention.activities_days", "general.auto_backup"],
        "changes": {
          "retention.activities_days": { "old": "90", "new": "60" },
          "general.auto_backup": { "old": "false", "new": "true" }
        }
      },
      "ip_address": "192.168.1.100",
      "created_at": 1709524800
    },
    {
      "id": 1522,
      "action": "auto_backup",
      "actor": "scheduler",
      "actor_id": null,
      "detail": {
        "path": "/var/lib/mission-control/backups/mc-backup-2026-03-04_03-00-00.db",
        "size": 2097152
      },
      "ip_address": null,
      "created_at": 1709524800
    },
    {
      "id": 1521,
      "action": "user_created",
      "actor": "admin",
      "actor_id": 1,
      "detail": {
        "username": "operator_jane",
        "role": "operator"
      },
      "ip_address": "192.168.1.100",
      "created_at": 1709520000
    }
  ],
  "total": 1523,
  "limit": 100,
  "offset": 0
}

Event Types

Audit events are categorized by action type. Each type has specific detail fields.

Authentication & User Management

login

User login event

• actor: Username
• detail: Object with success boolean

logout

User logout event

• actor: Username

user_created

New user account created

• actor: Admin username
• detail:

user_updated

User account modified

• actor: Admin username
• detail:

user_deleted

User account deleted

• actor: Admin username
• detail:

Settings & Configuration

settings_update

System settings modified

• actor: Admin username
• detail: Object with updated keys array and changes object

settings_reset

Setting reset to default value

• actor: Admin username
• detail:

Backup & Maintenance

backup_create

Manual backup created via API

• actor: Admin username
• detail:

backup_delete

Backup file deleted

• actor: Admin username
• detail:

auto_backup

Scheduled automatic backup

• actor: scheduler
• detail:

auto_cleanup

Scheduled data cleanup

• actor: scheduler
• detail:

Agents & Tasks

agent_created

New agent registered

• actor: Username or system
• detail:

agent_deleted

Agent removed

• actor: Admin username
• detail:

heartbeat_check

Scheduled heartbeat check marked agents offline

• actor: scheduler
• detail: Object with marked_offline array

task_created

New task created

• actor: Username
• detail:

task_assigned

Task assigned to agent

• actor: Username
• detail:

Pagination Example

Query large audit logs using offset-based pagination:

# First page (0-99)
curl -X GET "https://your-domain.com/api/audit?limit=100&offset=0" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

# Second page (100-199)
curl -X GET "https://your-domain.com/api/audit?limit=100&offset=100" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

# Third page (200-299)
curl -X GET "https://your-domain.com/api/audit?limit=100&offset=200" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

Time Range Queries

Query events within a specific time window:

# Events from the last 24 hours
SINCE=$(date -d '24 hours ago' +%s)
curl -X GET "https://your-domain.com/api/audit?since=$SINCE" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

# Events from March 2026
SINCE=$(date -d '2026-03-01' +%s)
UNTIL=$(date -d '2026-04-01' +%s)
curl -X GET "https://your-domain.com/api/audit?since=$SINCE&until=$UNTIL" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

Actor Filtering

Track actions by specific users or system processes:

# All actions by admin user
curl -X GET "https://your-domain.com/api/audit?actor=admin" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

# All automated scheduler actions
curl -X GET "https://your-domain.com/api/audit?actor=scheduler" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

# All system-initiated events
curl -X GET "https://your-domain.com/api/audit?actor=system" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

Error Responses

400 Bad Request

Invalid query parameters (e.g., limit exceeds maximum)

401 Unauthorized

User is not authenticated. Check session cookie.

403 Forbidden

User does not have admin role. Only admins can access audit logs.

Audit Log Retention

Audit events are automatically cleaned up based on the retention.audit_log_days setting:

• Default retention: 180 days
• Cleanup runs daily at 4:00 AM UTC when general.auto_cleanup is enabled
• Change retention period via Settings API:
  curl -X PUT https://your-domain.com/api/settings \
    -H "Cookie: mc-session=YOUR_SESSION_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"settings": {"retention.audit_log_days": "365"}}'
  

Security Considerations

1. Access Control: Only admin users can query audit logs
2. IP Logging: User actions include source IP addresses
3. Immutable Records: Audit events cannot be modified or deleted via API
4. Tamper Detection: Monitor settings_update events for unauthorized configuration changes
5. Compliance: Retain logs for regulatory requirements using the retention setting

Common Use Cases

Security Monitoring

# Failed login attempts
curl -X GET "https://your-domain.com/api/audit?action=login" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

# User privilege changes
curl -X GET "https://your-domain.com/api/audit?action=user_updated" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

Change Tracking

# Configuration changes in the last week
SINCE=$(date -d '7 days ago' +%s)
curl -X GET "https://your-domain.com/api/audit?action=settings_update&since=$SINCE" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

Backup Verification

# Recent backup operations
curl -X GET "https://your-domain.com/api/audit?action=auto_backup&limit=10" \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"