Skip to main content
ALTCHA®

Audit logs

The audit log records every sign-in attempt and every successful change made through the management API, by a user session or a full API key. Use it to answer who changed what, and when, and to investigate failed sign-ins.

What is recorded

Eventactionoutcome
Password sign-in (POST /v2/auth/login)auth.loginsuccess, failure, or otp_required
LDAP sign-in (POST /v2/auth/ldap)auth.ldapsuccess, failure, or otp_required
OTP step (POST /v2/auth/login/otp)auth.otpsuccess or failure
Passkey step (POST /v2/auth/login/passkey)auth.passkeysuccess or failure
OAuth callback (GET /v2/auth/oauth/{provider}/callback)auth.oauthsuccess, failure, or otp_required; details.provider names the provider
Own password change (POST /v2/me/password)user.change_passwordsuccess, or failure with code INCORRECT_PASSWORD
Failed step-up check (POST /v2/me/verify)user.verifyfailure with code INCORRECT_OTP or PASSKEY_VERIFICATION_FAILED; successes aren't recorded
Create, update, or deleteaccount.*, role.*, user.*, security_group.*, api_key.*, threat_source.*, threat_entry.*, training_data.* (training samples), each with .create, .update, .deletesuccess
Other changesuser.enable_otp, user.disable_otp, user.revoke_sessions (log out everywhere), user.add_passkey, user.delete_passkey, threat_source.refresh, remote_file.refresh, training_data.import, training_suggestion.accept, training_suggestion.delete, push_subscription.create, push_subscription.deletesuccess

Not recorded: plain logout (POST /v2/auth/logout); sign-in requests rejected by the rate limit (429) or with a malformed body (400); denied or invalid management requests; reads, searches, and status checks; and calls to API-key endpoints such as the widget endpoints, POST /v2/classifier, POST /v2/threat/_report, and POST /v2/training-data/_feedback.

Failed sign-ins also feed the brute_force and user_brute_force alerts, whether or not audit logs are enabled or licensed.

Entry fields

FieldTypeDescription
idstringaud_…
timestringRFC 3339
actionstringSee What is recorded
outcomestringsuccess, failure, or otp_required
codestring | nullThe error code of a failure, such as INVALID_CREDENTIALS, INCORRECT_OTP, USER_DISABLED, or OAUTH_FAILED; null otherwise
userIdstring | nullThe acting user. For a sign-in, the user with the typed username, or null when there's none. Users that LDAP or OAuth create on first sign-in get no separate entry; the sign-in entry carries their id.
usernamestring | nullThe acting user's name, or for a sign-in the typed username (at most 200 characters)
apiKeyIdstring | nullThe full API key that made the change; userId and username are then null
accountIdstring | nullThe account the change belongs to; null for sign-ins and for users, roles, threat sources, threat entries, and remote files
resourceIdstring | nullThe changed resource's id
changedFieldsstring[] | nullThe names of the request body's top-level fields, sorted; null for sign-ins. Field values are never stored.
detailsobject | nullExtra data for some actions: provider for auth.oauth, created and skipped for training_data.import, sampleId and duplicate for training_suggestion.accept, userId when root manages another user's passkeys
ipstring | nullThe client IP
userAgentstring | nullThe User-Agent header

With [privacy] anonymize_ip = true, public client IPs in ip are anonymized as in request logs (203.0.113.77 becomes 203.0.113.0); private IPs are kept. The default stores every IP in full. See Privacy & data handling.

Retention

[audit_logs]
retention = "365d"   # keep entries for a year (1d-3650d)

Entries older than [audit_logs] retention (default 90d) are deleted hourly, by one replica at a time. With enabled = false, nothing new is recorded, but search and retention keep working, so earlier entries stay searchable until they expire. To keep entries longer, export them with the search endpoint or include them in snapshots.

Search the audit log

POST /v2/audit-logs/_search is root only and accepts only an admin session: a non-root user gets 403 ROOT_PRIVILEGES_REQUIRED, and an API key gets 401 UNAUTHORIZED. In the admin UI, root users find the log under Audit Logs.

curl -X POST https://sentinel.example.com/v2/audit-logs/_search \
  -H 'Authorization: Bearer <jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "sortDir": "desc", "limit": 50 }'
{
  "data": [
    {
      "id": "aud_…",
      "time": "2026-11-19T09:25:59.325000+00:00",
      "action": "account.create",
      "outcome": "success",
      "code": null,
      "userId": "usr_…",
      "username": "root",
      "apiKeyId": null,
      "accountId": "acc_…",
      "resourceId": "acc_…",
      "changedFields": ["name"],
      "details": null,
      "ip": "127.0.0.1",
      "userAgent": "curl/8.7.1"
    },
    {
      "id": "aud_…",
      "time": "2026-11-19T09:25:45.600000+00:00",
      "action": "auth.login",
      "outcome": "failure",
      "code": "INVALID_CREDENTIALS",
      "userId": "usr_…",
      "username": "root",
      "apiKeyId": null,
      "accountId": null,
      "resourceId": null,
      "changedFields": null,
      "details": null,
      "ip": "127.0.0.1",
      "userAgent": "curl/8.7.1"
    },
    …
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 6 }
}
  • filter.accountId (optional) returns one account's entries; an id that isn't an account id returns 400 VALIDATION_ERROR.
  • Entries are sorted by time, the only sortBy value. sortDir defaults to asc, so pass "desc" for newest first.
  • limit (1–200, default 100) and offset paginate.

See POST /v2/audit-logs/_search in the API reference.

Start typing to search...

↑ ↓ Navigate ↵ Select