LumiBaseDocs

Security History and New-Device Sign-in Email

Audience: staff using the Studio, frontend developers building a member account page, and operators configuring email.

TL;DR: every signed-in user can read their own security events — sign-ins, failed attempts, new devices, password and two-factor changes, signed-out sessions — from GET /api/v1/me/security-history, and export them as CSV or JSON. A sign-in from a device the account has not used before sends an email to the account owner.

1. What the history contains

The history is read from the security audit log (lumibase_audit_log). Only the audit events below are ever returned, each under a friendly kind. Other audit events, such as setup, policy changes or exports, are never shown.

kindAudit eventRecorded when
sign_inlogin_successA password or TOTP sign-in succeeded. details.method is password or totp.
sign_in_failedlogin_failedA wrong password was entered for the account. details.reason gives the cause.
mfa_challenge_failedmfa_verify_failedA wrong two-factor code was entered.
new_devicenew_device_loginA sign-in came from a device the account had not used before (see §3). details.notified says whether the email was sent.
suspicious_sign_inanomaly_triggeredThe anomaly detector flagged a sign-in.
account_lockeduser_lockedToo many failed attempts locked the account.
account_unlockeduser_unlockedAn administrator unlocked the account.
password_changedpassword_changedThe password was changed from the profile.
password_reset_requestedpassword_reset_requestedA reset link was requested.
password_resetpassword_reset_completedThe password was reset through a link.
mfa_enabledmfa_enrolledTwo-factor authentication was turned on.
mfa_disabledmfa_disabledTwo-factor authentication was turned off.
session_revokedsession_revokedOne session was signed out.
sessions_revokedsessions_revokedOther sessions, or all of them, were signed out.
session_token_reuserefresh_token_reuse_detectedA refresh token was used twice, so the session was ended.

The kinds are defined once in packages/contracts/src/security-history.ts and mapped in apps/cms/src/modules/security-history/events.ts.

Redaction

  • Your events only. The subject of each audit row is resolved from metadata.targetUserId, then metadata.userId, then the target email, then the actor email. An administrator's action on someone else never appears in the administrator's own history. Rows older than the account are excluded, so failed attempts against an address before it was registered stay hidden.
  • Approximate IP. ipApprox keeps the network part only: 203.0.113.x for IPv4, the first 48 bits (2001:db8:85a3::/48) for IPv6.
  • Other people's details are dropped. When an administrator performed the action (for example account_unlocked), the item carries no IP, User-Agent or country.
  • No secrets. details is a per-kind allow-list of small values. Session ids, token ids, request ids, emails and anomaly scores are never returned.

2. API

Both endpoints require a signed-in user. They work for staff (studio tokens) and for members (frontend tokens). An API key or anonymous caller gets 401.

GET /api/v1/me/security-history

QueryDefaultMeaning
limit25Page size, 1–100.
cursor—The meta.nextCursor of the previous page.
scopesitesite or account, see below.
json
{
  "data": [
    {
      "id": "0193…",
      "kind": "new_device",
      "occurredAt": "2026-11-14T10:00:00.000Z",
      "siteId": "site_abc",
      "ipApprox": "203.0.113.x",
      "userAgent": "Mozilla/5.0 (Linux; Android 14; Pixel 8) …",
      "countryCode": "VN",
      "details": { "deviceLabel": "Chrome on Android", "notified": true }
    }
  ],
  "meta": { "nextCursor": "MjAyNi0xMS0xNFQxMDowMDowMC4wMDBafDAxOTM…", "limit": 25, "scope": "site" }
}

Items are newest first. nextCursor is null on the last page. A malformed cursor, limit or scope returns 400 VALIDATION_ERROR.

GET /api/v1/me/security-history/export

?format=json (default) or ?format=csv, plus scope. The response is a download (Content-Disposition: attachment) of every event in scope, newest first, up to 5,000 rows; X-Export-Truncated: true says the cap was hit. JSON comes as { data, meta: { exportedAt, count, truncated, scope } }. CSV has the columns occurredAt,kind,siteId,ipApprox,countryCode,userAgent,details; cells starting with =, +, - or @ get a leading ' so a spreadsheet does not run them as formulas. Exports are limited to 10 per user per 15 minutes (429 RATE_LIMITED).

Users with several sites

Each request runs under one site (X-Lumi-Site), and every audit row is stored with the site it was recorded under.

  • scope=site (default) returns the events recorded under the current site.
  • scope=account also returns events from every site the user is a direct member of (lumibase_user_sites). Use it to see account-wide changes made through another site: the password, two-factor setting and lockout state belong to the account, not to one site. Rows of sites the user does not belong to are never read. Each item carries its siteId.

The history is kept as long as the audit log keeps it: LUMIBASE_AUDIT_RETENTION_DAYS, 90 days by default.

3. New-device sign-in email

After a successful sign-in, by password or by password plus TOTP, the server checks whether the device is new for the account. If it is, it emails the account's own address.

What counts as a device. The anomaly detector's device fingerprint: a SHA-256 of the User-Agent with version numbers removed, plus the Accept-Language header (apps/cms/src/modules/anomaly/device.ts). Known devices are the last 20 fingerprints kept in lumibase_login_baselines.device_fingerprints. No extra table is used. A browser update does not make a new device. The IP address is not part of the key, because home and mobile IPs change often; it is reported in the email instead. The device is learned even when the anomaly detector's device check is turned off in the lockout policy.

When the email is sent. All of these must be true:

  • the account has signed in successfully before;
  • at least one device is already recorded for it, so the first sign-in after upgrading records the device without sending an email;
  • the fingerprint is not among the known devices;
  • the request has a User-Agent.

What it says. The time, the device label (for example "Chrome on Android"), the approximate IP and country, and where to sign the session out: for staff, Settings → Security → Active sessions in the Studio, linked when LUMIBASE_SECURITY_SETTINGS_URL is set; for members, the site URL. It never contains a token, session id or the full IP. A site can replace the built-in text with an email template whose key is new_device_login. The template variables are email, siteName, siteUrl, signedInAt, signedInAtText, ipApprox, country, device and securityUrl.

Delivery. The email is sent after the response, so sign-in never waits for the mail server. On Cloudflare Workers the send runs under waitUntil; on Docker it runs detached in the same process. It normally leaves within seconds of the sign-in. Email must be configured (SMTP or MailChannels); without it, the event is still recorded with notified: false.

Limits and privacy. At most 3 new-device emails per user per hour. Further new devices in that hour are still recorded in the history (notified: false). The email goes only to the account owner, after the password (and code) were accepted. The sign-in response, its status and its timing are the same whether or not an email is sent, so the feature reveals nothing about whether an account exists.

VariableDefaultPurpose
LUMIBASE_SECURITY_SETTINGS_URLunsetAbsolute URL of the Studio security page, for example https://cms.example.com/settings/security#active-sessions. Linked from the email sent to staff.

4. Studio

Settings → Security → Security history lists the events with the device name, approximate IP and country. Events worth a second look (failed attempts, new devices, flagged sign-ins, lockouts, token reuse) are marked Review. A selector switches between This site and All my sites, and Export CSV / Export JSON download the file through the export endpoint.

Last modified: 15/11/2026