Admin API

This endpoint requires admin-level roles (platform_admin, tenant_admin, or system_admin). Accessible via the API gateway at /v1/platform/*.

Audit Logs API

Comprehensive audit logging for compliance, security monitoring, and activity tracking.

Overview

Attribute	Value
Base Path	`/api/v1/audit`
Authentication	Bearer Token
Required Roles	`platform_admin`, `system_admin`, `super_admin`

Audit Events

Query Audit Logs

GET /api/v1/audit/events

Query Parameters

Parameter	Type	Description
`start_time`	datetime	Period start (required)
`end_time`	datetime	Period end
`actor_id`	uuid	Filter by user who performed action
`actor_type`	string	`user`, `api_key`, `system`, `integration`
`resource_type`	string	Filter by resource type
`resource_id`	uuid	Filter by specific resource
`action`	string	Filter by action type
`severity`	string	`info`, `warning`, `critical`
`outcome`	string	`success`, `failure`, `denied`
`ip_address`	string	Filter by IP address

Response

{
  "events": [
    {
      "id": "evt_001",
      "timestamp": "2026-01-24T19:30:45.123Z",
      "actor": {
        "id": "user_001",
        "type": "user",
        "email": "admin@example.com",
        "name": "John Admin",
        "role": "admin"
      },
      "action": "user.role.update",
      "resource": {
        "type": "user",
        "id": "user_050",
        "name": "Sarah Employee"
      },
      "changes": {
        "role": {
          "from": "server",
          "to": "shift_lead"
        }
      },
      "context": {
        "location_id": "loc_123",
        "tenant_id": "tenant_abc",
        "ip_address": "192.168.1.100",
        "user_agent": "Mozilla/5.0...",
        "session_id": "sess_xyz"
      },
      "outcome": "success",
      "severity": "info"
    },
    {
      "id": "evt_002",
      "timestamp": "2026-01-24T19:28:12.456Z",
      "actor": {
        "id": "user_005",
        "type": "user",
        "email": "manager@example.com"
      },
      "action": "order.void",
      "resource": {
        "type": "order",
        "id": "ord_12345"
      },
      "metadata": {
        "order_total": 125.50,
        "reason": "customer_complaint",
        "manager_override": true
      },
      "context": {
        "location_id": "loc_123",
        "ip_address": "192.168.1.105"
      },
      "outcome": "success",
      "severity": "warning"
    },
    {
      "id": "evt_003",
      "timestamp": "2026-01-24T19:25:00.789Z",
      "actor": {
        "id": "user_099",
        "type": "user",
        "email": "unknown@example.com"
      },
      "action": "auth.login",
      "resource": {
        "type": "session"
      },
      "context": {
        "ip_address": "203.0.113.50",
        "user_agent": "curl/7.64.1",
        "geo_location": {
          "country": "CN",
          "city": "Shanghai"
        }
      },
      "outcome": "denied",
      "reason": "invalid_credentials",
      "severity": "critical",
      "alerts_triggered": ["suspicious_login_attempt"]
    }
  ],
  "pagination": {
    "total": 15420,
    "page": 1,
    "limit": 100,
    "has_more": true
  }
}

Get Audit Event

GET /api/v1/audit/events/{event_id}

Response

{
  "id": "evt_001",
  "timestamp": "2026-01-24T19:30:45.123Z",
  "actor": {
    "id": "user_001",
    "type": "user",
    "email": "admin@example.com",
    "name": "John Admin",
    "role": "admin",
    "permissions": ["users:write", "roles:manage"]
  },
  "action": "user.role.update",
  "action_category": "user_management",
  "resource": {
    "type": "user",
    "id": "user_050",
    "name": "Sarah Employee",
    "path": "/tenants/tenant_abc/users/user_050"
  },
  "changes": {
    "role": {
      "from": "server",
      "to": "shift_lead"
    },
    "permissions": {
      "from": ["orders:read", "orders:write"],
      "to": ["orders:read", "orders:write", "schedule:read", "reports:read"]
    }
  },
  "context": {
    "tenant_id": "tenant_abc",
    "location_id": "loc_123",
    "ip_address": "192.168.1.100",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
    "session_id": "sess_xyz",
    "request_id": "req_abc123",
    "correlation_id": "corr_def456"
  },
  "outcome": "success",
  "severity": "info",
  "compliance": {
    "regulations": ["SOC2", "PCI-DSS"],
    "retention_days": 2555
  },
  "related_events": [
    {
      "id": "evt_000",
      "action": "user.view",
      "timestamp": "2026-01-24T19:30:30.000Z"
    }
  ]
}

Export Audit Logs

POST /api/v1/audit/export

Request Body

{
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": "2026-01-24T23:59:59Z",
  "filters": {
    "action_categories": ["user_management", "payment_processing"],
    "severity": ["warning", "critical"]
  },
  "format": "csv",
  "include_fields": [
    "timestamp",
    "actor.email",
    "action",
    "resource.type",
    "resource.id",
    "outcome",
    "ip_address"
  ],
  "delivery": {
    "method": "email",
    "recipients": ["compliance@example.com"]
  }
}

Response

{
  "export_id": "export_001",
  "status": "processing",
  "estimated_records": 15420,
  "estimated_completion": "2026-01-24T19:45:00Z"
}

Activity Streams

Get User Activity

GET /api/v1/audit/users/{user_id}/activity

Query Parameters

Parameter	Type	Description
`start_time`	datetime	Period start
`end_time`	datetime	Period end
`limit`	integer	Max results (default 100)

Response

{
  "user_id": "user_001",
  "period": {
    "start": "2026-01-24T00:00:00Z",
    "end": "2026-01-24T23:59:59Z"
  },
  "summary": {
    "total_actions": 145,
    "sessions": 3,
    "locations_accessed": ["loc_123", "loc_456"],
    "ip_addresses": ["192.168.1.100", "10.0.0.50"]
  },
  "timeline": [
    {
      "timestamp": "2026-01-24T08:15:00Z",
      "action": "auth.login",
      "details": "Logged in from 192.168.1.100"
    },
    {
      "timestamp": "2026-01-24T08:16:00Z",
      "action": "report.view",
      "details": "Viewed Daily Sales Report"
    },
    {
      "timestamp": "2026-01-24T08:30:00Z",
      "action": "schedule.update",
      "details": "Modified schedule for week of Jan 27"
    }
  ],
  "risk_indicators": []
}

Get Resource History

GET /api/v1/audit/resources/{resource_type}/{resource_id}/history

Response

{
  "resource": {
    "type": "menu_item",
    "id": "item_001",
    "name": "Ribeye Steak"
  },
  "changes": [
    {
      "timestamp": "2026-01-24T15:00:00Z",
      "actor": {
        "id": "user_010",
        "email": "chef@example.com"
      },
      "action": "menu_item.update",
      "changes": {
        "price": {"from": 35.00, "to": 38.00},
        "description": {"from": "12oz ribeye...", "to": "14oz prime ribeye..."}
      }
    },
    {
      "timestamp": "2026-01-20T10:00:00Z",
      "actor": {
        "id": "user_010",
        "email": "chef@example.com"
      },
      "action": "menu_item.update",
      "changes": {
        "available": {"from": true, "to": false}
      }
    },
    {
      "timestamp": "2025-06-01T00:00:00Z",
      "actor": {
        "id": "user_001",
        "email": "admin@example.com"
      },
      "action": "menu_item.create",
      "changes": {
        "created": true
      }
    }
  ],
  "total_changes": 15
}

Compliance Reports

Generate Compliance Report

POST /api/v1/audit/compliance/reports

Request Body

{
  "report_type": "access_review",
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-31"
  },
  "scope": {
    "tenant_id": "tenant_abc",
    "include_locations": ["loc_123", "loc_456"]
  },
  "standards": ["SOC2", "PCI-DSS"],
  "include_sections": [
    "user_access_changes",
    "privileged_actions",
    "failed_authentications",
    "data_exports",
    "configuration_changes"
  ]
}

Response

{
  "report_id": "report_001",
  "status": "generating",
  "estimated_completion": "2026-01-24T20:00:00Z"
}

Get Compliance Report

GET /api/v1/audit/compliance/reports/{report_id}

Response

{
  "report_id": "report_001",
  "report_type": "access_review",
  "status": "completed",
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-31"
  },
  "generated_at": "2026-01-24T20:00:00Z",
  "summary": {
    "total_events": 125420,
    "critical_events": 12,
    "warnings": 45,
    "compliance_score": 98.5
  },
  "sections": {
    "user_access_changes": {
      "new_users": 5,
      "terminated_users": 2,
      "role_changes": 15,
      "permission_grants": 28,
      "permission_revocations": 12
    },
    "privileged_actions": {
      "total": 450,
      "by_action": {
        "user.delete": 2,
        "role.create": 3,
        "payment.refund": 45,
        "config.update": 12
      }
    },
    "failed_authentications": {
      "total": 125,
      "unique_users": 45,
      "suspicious_patterns": 3
    },
    "data_exports": {
      "total": 28,
      "by_type": {
        "customer_data": 5,
        "financial_reports": 15,
        "employee_records": 8
      }
    }
  },
  "findings": [
    {
      "severity": "warning",
      "finding": "3 users have not logged in for 30+ days but retain active access",
      "recommendation": "Review and disable inactive accounts",
      "affected_users": ["user_045", "user_067", "user_089"]
    },
    {
      "severity": "info",
      "finding": "All privileged actions were performed by authorized users",
      "status": "compliant"
    }
  ],
  "download_url": "https://..."
}

Retention Policies

Get Retention Policy

GET /api/v1/audit/retention

Response

{
  "policies": [
    {
      "event_category": "authentication",
      "retention_days": 365,
      "archive_after_days": 90,
      "compliance_requirement": "SOC2"
    },
    {
      "event_category": "payment_processing",
      "retention_days": 2555,
      "archive_after_days": 365,
      "compliance_requirement": "PCI-DSS"
    },
    {
      "event_category": "user_management",
      "retention_days": 2555,
      "archive_after_days": 365,
      "compliance_requirement": "SOC2"
    },
    {
      "event_category": "general",
      "retention_days": 365,
      "archive_after_days": 90
    }
  ],
  "storage": {
    "active_events": 15420000,
    "archived_events": 125000000,
    "storage_used_gb": 45.2
  }
}

Update Retention Policy

PUT /api/v1/audit/retention

Request Body

{
  "event_category": "custom_category",
  "retention_days": 730,
  "archive_after_days": 180
}

Alerts

Get Audit Alerts

GET /api/v1/audit/alerts

Response

{
  "alerts": [
    {
      "id": "alert_001",
      "name": "Multiple Failed Logins",
      "trigger": {
        "event_type": "auth.login",
        "outcome": "failure",
        "threshold": 5,
        "window_minutes": 15
      },
      "notifications": ["email", "slack"],
      "status": "active",
      "triggered_count_24h": 3
    },
    {
      "id": "alert_002",
      "name": "High Value Refund",
      "trigger": {
        "event_type": "payment.refund",
        "condition": "metadata.amount > 500"
      },
      "notifications": ["email"],
      "status": "active",
      "triggered_count_24h": 1
    },
    {
      "id": "alert_003",
      "name": "After Hours Access",
      "trigger": {
        "event_type": "auth.login",
        "condition": "time_of_day NOT BETWEEN '06:00' AND '23:00'"
      },
      "notifications": ["slack"],
      "status": "active",
      "triggered_count_24h": 0
    }
  ]
}

Create Audit Alert

POST /api/v1/audit/alerts

Request Body

{
  "name": "Unusual Data Export",
  "description": "Alert when large data exports occur",
  "trigger": {
    "event_type": "data.export",
    "condition": "metadata.record_count > 10000"
  },
  "notifications": {
    "channels": ["email", "slack"],
    "recipients": ["security@example.com"],
    "slack_channel": "#security-alerts"
  },
  "enabled": true
}

Webhooks

Event	Description
`audit.critical_event`	Critical severity event logged
`audit.alert_triggered`	Audit alert triggered
`audit.compliance_violation`	Potential compliance violation
`audit.export_completed`	Audit log export completed

Error Responses

Status	Code	Description
400	`invalid_time_range`	Invalid time range specified
403	`audit_access_denied`	Insufficient audit permissions
404	`event_not_found`	Audit event not found
429	`query_rate_limited`	Too many audit queries

Users API - User management
Roles API - Role management
Threat Detection API - Security monitoring

Overview​

Audit Events​

Query Audit Logs​

Get Audit Event​

Export Audit Logs​

Activity Streams​

Get User Activity​

Get Resource History​

Compliance Reports​

Generate Compliance Report​

Get Compliance Report​

Retention Policies​

Get Retention Policy​

Update Retention Policy​

Alerts​

Get Audit Alerts​

Create Audit Alert​

Webhooks​

Error Responses​

Related Documentation​

Overview

Audit Events

Query Audit Logs

Get Audit Event

Export Audit Logs

Activity Streams

Get User Activity

Get Resource History

Compliance Reports

Generate Compliance Report

Get Compliance Report

Retention Policies

Get Retention Policy

Update Retention Policy

Alerts

Get Audit Alerts

Create Audit Alert

Webhooks

Error Responses

Related Documentation