Audit Logs

GET  /orgs/{orgId}/api/v1/admin/audit-logs
GET  /orgs/{orgId}/api/v1/admin/audit-logs/{logId}
GET  /orgs/{orgId}/api/v1/admin/audit-logs/stats
GET  /orgs/{orgId}/api/v1/admin/audit-logs/actions
GET  /orgs/{orgId}/api/v1/admin/audit-logs/export
GET  /orgs/{orgId}/api/v1/admin/audit-logs/retention
PUT  /orgs/{orgId}/api/v1/admin/audit-logs/retention

The audit log provides an immutable, tamper-evident record of all actions performed within a organization — by users, administrators, agents, and the LumoAuth platform itself.

Authentication

All audit log endpoints require a valid admin API key or a Bearer token issued to a user with settings.manage permission.

Audit Log Entry Object

Audit Log Entry
{
  "id": "01JF3KAUDIT...",
  "orgId": "acme-corp",
  "eventType": "user.login",
  "action": "login",
  "severity": "info",
  "actorId": "01JF3KUSER...",
  "actorType": "user",
  "actorEmail": "alice@example.com",
  "targetId": "01JF3KUSER...",
  "targetType": "user",
  "ipAddress": "203.0.113.1",
  "userAgent": "Mozilla/5.0 ...",
  "result": "success",
  "metadata": {
    "mfaMethod": "totp",
    "clientId": "my-app"
  },
  "createdAt": "2026-03-01T08:00:00Z"
}

List Audit Logs

List Audit Logs
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/audit-logs?startDate=2026-03-01T00:00:00Z&limit=50" \
  -H "Authorization: ApiKey lmk_abc123"

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 20, max: 100)
`search`	string	Full-text search across log fields
`userId` or `actorId`	string	Filter by actor (user/agent/admin)
`targetId`	string	Filter by target resource
`resourceType` or `targetType`	string	Filter by target resource type
`action`	string	Filter by action (e.g. `login`)
`severity`	string	Filter by severity (`info`, `warning`, `error`)
`result`	string	`success` or `failure`
`startDate` or `from`	ISO 8601	Start of date range
`endDate` or `to`	ISO 8601	End of date range
`ipAddress`	string	Filter by source IP address

List Response
{
  "data": {
    "data": [
      {
        "id": "01JF3KAUDIT...",
        "eventType": "user.login",
        "actorEmail": "alice@example.com",
        "ipAddress": "203.0.113.1",
        "result": "success",
        "createdAt": "2026-03-01T08:00:00Z"
      }
    ],
    "meta": { "total": 2847, "page": 1, "limit": 50, "totalPages": 57 }
  }
}

Get Single Log Entry

Get a Single Log Entry
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/audit-logs/01JF3KAUDIT..." \
  -H "Authorization: ApiKey lmk_abc123"

Audit Log Statistics

Get Statistics
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/audit-logs/stats" \
  -H "Authorization: ApiKey lmk_abc123"

Query Parameters for Stats

Parameter	Description
`groupBy`	Group by `action` or `user`
`startDate` / `from`	Start of time window
`endDate` / `to`	End of time window

List Available Actions

Returns a distinct list of all action types present in the audit log for the organization.

List Available Actions
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/audit-logs/actions" \
  -H "Authorization: ApiKey lmk_abc123"

Actions Response
{
  "data": {
    "data": ["login", "logout", "user.created", "token.issued", "password.changed"]
  }
}

Export Audit Logs

Export is synchronous for small datasets (returns 200) or queued for large exports (returns 202).

Export as CSV
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/audit-logs/export?format=csv&startDate=2026-01-01T00:00:00Z&endDate=2026-03-31T23:59:59Z" \
  -H "Authorization: ApiKey lmk_abc123" \
  -o audit-logs-q1-2026.csv

Export as JSON
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/audit-logs/export?format=json&startDate=2026-01-01T00:00:00Z&endDate=2026-03-31T23:59:59Z" \
  -H "Authorization: ApiKey lmk_abc123" \
  -o audit-logs-q1-2026.json

Export Parameters

Parameter	Values	Default
`format`	`csv`, `json`	`csv`
`startDate` / `from`	ISO 8601	—
`endDate` / `to`	ISO 8601	—

Exports are limited to 10,000 records per request.

Retention Settings

Get Retention Settings

Get Retention Settings
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/audit-logs/retention" \
  -H "Authorization: ApiKey lmk_abc123"

Retention Response
{
  "data": {
    "data": {
      "retentionDays": 90,
      "autoDelete": true
    }
  }
}

Update Retention Settings

Update Retention Settings
curl -X PUT https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/audit-logs/retention \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "retentionDays": 365,
    "autoDelete": true
  }'

Common Event Types

Event	Description
`user.login`	Successful user authentication
`user.login_failed`	Failed authentication attempt
`user.logout`	User signed out
`user.created`	New user provisioned
`user.updated`	User profile updated
`user.deleted`	User deleted
`user.blocked`	User account blocked
`user.password_changed`	Password changed
`user.mfa_enabled`	MFA enabled for user
`token.issued`	OAuth token issued
`token.revoked`	OAuth token revoked
`client.created`	OAuth client registered
`admin.action`	Administrative action by organization admin
`super_admin.access`	Super admin accessed this organization
`role.assigned`	Role granted to user
`consent.granted`	User granted OAuth scope consent

warning

super_admin.access entries are automatically written whenever a platform super admin accesses or modifies organization data, providing a complete record of privileged access.

Authentication​

Audit Log Entry Object​

List Audit Logs​

Query Parameters​

Get Single Log Entry​

Audit Log Statistics​

Query Parameters for Stats​

List Available Actions​

Export Audit Logs​

Export Parameters​

Retention Settings​

Get Retention Settings​

Update Retention Settings​

Common Event Types​