# Audit logs

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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.

<Callout type="note" title="License required">

Recording needs the <code>audit_logs</code> license feature. Without it, nothing is recorded and startup logs a warning; existing entries stay searchable and keep expiring. Installing a license takes effect at once. See [Plans & Licensing](/docs/sentinel/v2/plans/).

## What is recorded

| Event | `action` | `outcome` |
| --- | --- | --- |
| Password sign-in (`POST /v2/auth/login`) | `auth.login` | `success`, `failure`, or `otp_required` |
| LDAP sign-in (`POST /v2/auth/ldap`) | `auth.ldap` | `success`, `failure`, or `otp_required` |
| OTP step (`POST /v2/auth/login/otp`) | `auth.otp` | `success` or `failure` |
| Passkey step (`POST /v2/auth/login/passkey`) | `auth.passkey` | `success` or `failure` |
| OAuth callback (`GET /v2/auth/oauth/{provider}/callback`) | `auth.oauth` | `success`, `failure`, or `otp_required`; `details.provider` names the provider |
| Own password change (`POST /v2/me/password`) | `user.change_password` | `success`, or `failure` with code `INCORRECT_PASSWORD` |
| Failed step-up check (`POST /v2/me/verify`) | `user.verify` | `failure` with code `INCORRECT_OTP` or `PASSKEY_VERIFICATION_FAILED`; successes aren't recorded |
| Create, update, or delete | `account.*`, `role.*`, `user.*`, `security_group.*`, `api_key.*`, `threat_source.*`, `threat_entry.*`, `training_data.*` (training samples), each with `.create`, `.update`, `.delete` | `success` |
| Other changes | `user.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.delete` | `success` |

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](/docs/sentinel/v2/operations/alerts/), whether or not audit logs are enabled or licensed.

## Entry fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | `aud_…` |
| `time` | string | RFC 3339 |
| `action` | string | See [What is recorded](#what-is-recorded) |
| `outcome` | string | `success`, `failure`, or `otp_required` |
| `code` | string \| null | The error code of a failure, such as `INVALID_CREDENTIALS`, `INCORRECT_OTP`, `USER_DISABLED`, or `OAUTH_FAILED`; `null` otherwise |
| `userId` | string \| null | The 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. |
| `username` | string \| null | The acting user's name, or for a sign-in the typed username (at most 200 characters) |
| `apiKeyId` | string \| null | The `full` API key that made the change; `userId` and `username` are then `null` |
| `accountId` | string \| null | The account the change belongs to; `null` for sign-ins and for users, roles, threat sources, threat entries, and remote files |
| `resourceId` | string \| null | The changed resource's id |
| `changedFields` | string[] \| null | The names of the request body's top-level fields, sorted; `null` for sign-ins. Field **values are never stored**. |
| `details` | object \| null | Extra 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 |
| `ip` | string \| null | The client IP |
| `userAgent` | string \| null | The `User-Agent` header |

With [`[privacy] anonymize_ip = true`](/docs/sentinel/v2/reference/configuration/#privacy), 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](/docs/sentinel/v2/security/privacy/).

## Retention

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

Entries older than [`[audit_logs] retention`](/docs/sentinel/v2/reference/configuration/#audit_logs) (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](/docs/sentinel/v2/operations/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**.

```bash
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 }'
```

```json
{
"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`](/sentinel-api-docs-v2.html#tag/audit-logs/POST/v2/audit-logs/_search) in the API reference.

## Related

- [`[audit_logs]` in the Configuration reference](/docs/sentinel/v2/reference/configuration/#audit_logs)
- [Alerts](/docs/sentinel/v2/operations/alerts/)
- [Sign-in & SSO](/docs/sentinel/v2/security/sign-in/)
- [Privacy & data handling](/docs/sentinel/v2/security/privacy/)
- [API keys & access levels](/docs/sentinel/v2/concepts/api-keys/)
