Skip to content
Autentico

Trusted Devices

When MFA is enabled, users can check “Trust this device” after a successful MFA verification. Autentico sets a long-lived cookie on the browser — on future logins from the same browser, the MFA step is skipped automatically.

How it works

Section titled “How it works”
  1. User completes MFA successfully
  2. User checks the “Trust this device” checkbox before submitting the MFA form
  3. Autentico creates a trusted_devices record tied to the user and stores a random token in an HttpOnly cookie; only its SHA-256 hash is persisted
  4. On subsequent logins from the same browser, Autentico hashes the cookie, looks up the trusted device record, validates it, and bypasses the MFA challenge

The trusted_devices table stores metadata and a credential hash:

Field Description
id Public management ID, independent of the cookie token
token_hash Indexed SHA-256 hash of the cookie token; never returned by the account API
user_id User the device is trusted for
device_name User-agent string at trust time
created_at When the device was first trusted
last_used_at Last time the device skipped MFA
expires_at Expiry — after this the device must re-verify MFA

Configuration

Section titled “Configuration”
Setting Default Description
trust_device_enabled false Enable or disable the trusted device feature globally
trust_device_expiration 720h How long a trusted device remains valid (e.g. 168h = 7 days)

Both settings can be overridden per-client. See Per-Client Overrides.

Enabling trusted devices

Section titled “Enabling trusted devices”

In the Admin UI: Settings → set trust_device_enabled to true.

Via API:

Terminal window
curl -X PUT https://auth.example.com/admin/api/settings \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"trust_device_enabled": "true", "trust_device_expiration": "720h"}'

The effective per-client setting controls both the “Trust this device” checkbox and whether an existing cookie may bypass MFA during password or magic-link login. A client can disable trusted devices even when enabled globally, or enable them when globally disabled. See per-client overrides. New device records and cookies use that client’s trust duration. Shared SSO remains independent: a client with trusted devices disabled may reuse an already authenticated IdP session. Request prompt=login for a fresh login where its direct MFA policy is checked.

Managing trusted devices

Section titled “Managing trusted devices”

The account API lists public device IDs and metadata, and accepts those IDs for revocation. Neither an ID nor a stored hash can be used as a trusted-device cookie. Schema 20 upgrades existing devices without changing their cookies or expiry; no new key or re-enrollment is needed.

Trusted devices are cleared when:

  • The device record expires (expires_at passes)
  • The user explicitly logs out
  • An admin deactivates the user’s sessions
  • The background cleanup job removes expired records