Audit trail

Each realm with an auth section keeps an audit trail: one record per security-sensitive action or event, with who did it, to what, when and from where. It answers questions such as “who gave Bob the admin role?” or “which key created this user?”. Records can be read, but not changed or deleted: they expire after the realm’s retention period.

What is recorded#

Failed logins aren’t recorded here: they are throttled and counted, and every request is in the access log.

Records#

{
  "id": "d3cb1q0spovnshcrql9g",
  "at": "2026-09-27T12:00:00.000Z",
  "action": "role.add",
  "actor": "user:d3c9ljp8hc2g00b6s1m0",
  "target": "user:d3cb0m8spovnshcrqk90",
  "details": { "role": "editor" },
  "request_id": "d3cb1q0spovnshcrql8g",
  "client_ip": "192.0.2.10"
}

• actor is who acted: user:<id> (a session), key:<name> (an API key), anonymous (sign-ups and refused requests), config:realm.yaml (seeds applied at startup) or cli:bootstrap.
• target is what the action applied to: user:<id>, key:<name>, invitation:<id>, or null.
• request_id matches the request’s X-Request-ID and its line in the access log. client_ip follows TRUSTED_PROXIES.

Records name users by id, never by email, and never contain passwords or password hashes, session tokens, API keys, invitation tokens, or request bodies. A test checks this for every action.

Reading the trail#

With the CLI, as an administrator:

backd audit --realm blog --since 7d
# TIME                      ACTION         ACTOR                    TARGET                   CLIENT      DETAILS
# 2026-09-27T12:00:00.000Z  role.add       user:d3c9ljp8hc2g00b6s1m0  user:d3cb0m8spovnshcrqk90  192.0.2.10  role=editor
# …

backd audit --realm blog --user bob@example.com       # records about one user
backd audit --realm blog --action apikey.create --json

--action, --actor and --target filter exactly; --user looks up an existing user’s id (for a deleted user, use --target user:<id>); --since takes an RFC 3339 time or a duration back from now; --limit defaults to 50; --json prints one JSON record per line.

Over HTTP, GET /v1/{realm}/_admin/audit returns a page of records, newest first, with the query parameters action, actor, target, since, until, limit and skip (see the admin API). The JavaScript client has client.admin.audit.list(…).

Each record is also written to the log, as a line with "msg":"audit" and the same fields, so the trail reaches your log pipeline too. If a record can’t be stored, the action it describes has already happened; backd logs the record as an error ("msg":"audit record not stored") instead.

Retention#

Records are kept for one year by default. Set another period per realm in realm.yaml:

audit:
  retention: 180d   # at least 1d

Each record’s expiry is fixed when it’s written, so a new retention applies to records written from then on. MongoDB removes expired records (a TTL index on expires_at).

Records hold client IP addresses and user ids, which are personal data in many jurisdictions: choose a retention your privacy policy covers, and include the trail in answers to access requests.

Append-only#

• No endpoint or command changes or deletes records.
• In the production reference, backd’s own database user may only read and insert into the audit collection, so not even a compromised backd process can rewrite history.
• Records are stored in the realm’s system database and included in its backups.
• The trail doesn’t cover direct access to MongoDB: people with database credentials can do anything. Keep those credentials to the provisioning step, as the production reference does.