Skip to main content
The trusted device module lets you mark a device as trusted after a user completes two-factor authentication, then skip 2FA on subsequent sign-ins from that device. Trust is stored against an HMAC-signed fingerprint, not a plain device ID, so it cannot be guessed or forged. It is a standalone module, you call it yourself in your own sign-in flow, it does not wire into the twoFactor plugin automatically.
If you want trusted devices wired into sign-in for you, turn on signInGate.trustedDevice instead. The sign-in gate issues the device cookie, skips the second factor and adds list and revoke routes. This page covers the standalone module.

Setup

lib/theauth.ts

Fingerprint a request

generateFingerprint derives a stable, HMAC-protected fingerprint from the user-agent, accept-language, accept-encoding, and accept request headers. The same header values always produce the same fingerprint, and a browser update that changes them produces a new one:

Trust a device

After the user completes 2FA, call trustDevice to mark their device. It returns the trust record’s id (calling it again for the same fingerprint refreshes the expiry and returns the same id). Note that isTrusted looks devices up by user and fingerprint, not by this id, so the id is only useful if you want to keep a handle on the record, for example in a long-lived cookie:
Trust after 2FA (server)

Check whether a device is trusted

On sign-in, check isTrusted before prompting for a 2FA code:
Check on sign-in (server)

Revoke devices

Revoke one device / all devices (server)

List trusted devices

List devices (server)

Configuration reference

string
HMAC key used to sign device fingerprints. Rotate this to invalidate all trusted devices instantly. If omitted, a random per-process key is used and fingerprints won’t survive a restart.
number
default:2592000
How long a device stays trusted, in seconds. Default is 30 days.
number
default:10
Maximum number of trusted devices per user. The oldest records are evicted when exceeded.

Two-factor auth

TOTP plugin whose second-factor check you can skip on trusted devices in your own sign-in flow.

Multi-session

List and revoke a user’s sessions.

Compliance

Audit trail, GDPR tooling, and the other compliance-related features.

Sessions

Cookie and JWT sessions you issue after sign-in.
Last modified on October 13, 2026