Audit Logging

Autentico records security-relevant events in an audit log stored in the audit_logs table. The log captures who did what, when, and from where – providing a trail for security review, compliance, and incident investigation.

Configuration

curl -X PUT https://auth.example.com/admin/api/settings \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"audit_log_retention": "720h"}'

Setting	Default	Description
`audit_log_retention`	`720h` (30 days)	How long audit logs are kept. Set to `0` to disable logging, `-1` to keep logs forever.

When retention is set to 0 or empty, audit events are not recorded at all. The background cleanup job purges expired entries based on the retention duration.

Event types

Event	Target	Description
`login_success`	user	Successful password or federation login
`login_failed`	user	Failed login attempt
`mfa_success`	user	Successful MFA verification
`mfa_failed`	user	Failed MFA verification
`passkey_login_success`	user	Successful passkey authentication
`passkey_login_failed`	user	Failed passkey authentication
`password_changed`	user	User changed their password
`password_reset_requested`	user	Password reset email was sent
`password_reset_completed`	user	Password was successfully reset
`user_created`	user	New user account created
`user_updated`	user	User profile updated
`user_deactivated`	user	User account deactivated
`user_reactivated`	user	User account reactivated
`user_deleted`	user	User account permanently deleted
`user_unlocked`	user	User account unlocked after lockout
`mfa_enrolled`	user	User enrolled in TOTP MFA
`mfa_disabled`	user	TOTP MFA disabled for user
`passkey_added`	user	Passkey credential registered
`passkey_removed`	user	Passkey credential removed
`logout`	user	User logged out
`session_revoked`	session	Individual session revoked
`all_user_sessions_revoked`	session	All sessions for a user revoked
`other_sessions_revoked`	session	All sessions except current revoked
`token_revoked`	token	Token revoked
`client_created`	client	OAuth2 client registered
`client_updated`	client	OAuth2 client updated
`client_deleted`	client	OAuth2 client deleted
`settings_updated`	settings	System settings changed
`settings_imported`	settings	Settings imported from file
`protected_app_created`	protected_app	Protected application registered
`protected_app_updated`	protected_app	Protected application configuration replaced
`protected_app_deleted`	protected_app	Application removed and its sessions revoked
`federation_created`	federation	Federation provider added
`federation_updated`	federation	Federation provider updated
`federation_deleted`	federation	Federation provider removed
`deletion_approved`	user	Account deletion request approved
`group_created`	group	Group created
`group_updated`	group	Group updated
`group_deleted`	group	Group deleted
`group_member_added`	group	User added to a group; detail includes `user_id`
`group_member_removed`	group	User removed from a group; detail includes `user_id`
`group_claim_upserted`	group	Group claim created or updated; detail includes local `claim_name`, never its value
`group_claim_deleted`	group	Group claim deleted; detail includes local `claim_name`, never its value
`user_claim_upserted`	user	Custom claim created or updated; detail includes `claim_name`
`user_claim_deleted`	user	Custom claim deleted; detail includes `claim_name`

Group, membership and custom-claim events are recorded after a successful change, with the acting administrator, affected target and client IP. Rejected changes do not produce success events. Custom-claim values are never included in audit details. These events follow the same retention setting as other audit events and are available in the Admin UI event filter.

Querying audit logs

GET /admin/api/audit-logs

curl "https://auth.example.com/admin/api/audit-logs?event=login_failed&order=desc&limit=50" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Query parameters

Parameter	Default	Description
`event`	–	Filter by event type (e.g. `login_failed`, `user_created`)
`search`	–	Search across `actor_username`, `target_id`, `ip_address`, `detail`
`sort`	`created_at`	Sort field: `created_at`, `event`
`order`	`desc`	Sort order: `asc`, `desc`
`created_at_from`	–	Date range start (ISO 8601, e.g. `2026-01-01T00:00:00Z`)
`created_at_to`	–	Date range end (ISO 8601)
`limit`	`100`	Max results per page (1–100)
`offset`	`0`	Number of results to skip

Response

{
  "items": [
    {
      "id": "cq1abc123",
      "event": "login_failed",
      "actor_id": null,
      "actor_username": "",
      "target_type": "user",
      "target_id": "user-456",
      "detail": "{\"username\":\"alice\"}",
      "ip_address": "192.168.1.100",
      "created_at": "2026-05-09T14:30:00Z"
    }
  ],
  "total": 42
}

Examples

Failed logins in the last 24 hours:

curl "https://auth.example.com/admin/api/audit-logs?event=login_failed&created_at_from=2026-05-08T14:30:00Z" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

All events for a specific IP address:

curl "https://auth.example.com/admin/api/audit-logs?search=192.168.1.100" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Settings changes:

curl "https://auth.example.com/admin/api/audit-logs?event=settings_updated" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Audit log record structure

Each audit event stores the following fields in the audit_logs table:

Column	Type	Description
`id`	TEXT	Unique event ID (xid)
`event`	TEXT	Event type (see table above)
`actor_id`	TEXT	ID of the user who performed the action (nullable – null for failed logins)
`actor_username`	TEXT	Username of the actor at the time of the event
`target_type`	TEXT	Type of entity affected: `user`, `client`, `session`, `token`, `settings`, `federation`, `group`, `protected_app`
`target_id`	TEXT	ID of the affected entity
`detail`	TEXT	JSON string with additional context (e.g. `{"method":"federation","provider":"google"}`)
`ip_address`	TEXT	Client IP address
`created_at`	DATETIME	When the event occurred