Skip to content

docs: document MFA trusted devices #1489

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
charIeszhao merged 4 commits into from
Sep 4, 2026
Merged

docs: document MFA trusted devices #1489

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8b555f3
docs: document MFA trusted devices
charIeszhao Aug 25, 2026
442f7ff
docs: update trusted device opt-in flow
charIeszhao Sep 3, 2026
2be33fd
docs: explain trusting a device after skipping
charIeszhao Sep 3, 2026
e1d51ad
docs: simplify trusted device cookie guidance
charIeszhao Sep 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/developers/audit-logs/event-types.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,8 @@ Feel free to [contact us](https://logto.io/contact) if you’d like to share you
| Interaction.SignIn.Verification.Totp.Submit | Verify TOTP verification code |
| Interaction.SignIn.Verification.Webauthn.Create | Create WebAuthn authentication |
| Interaction.SignIn.Verification.WebAuthn.Submit | Verify WebAuthn authentication |
| TrustedDevice.Created | Create a trusted-device credential |
| TrustedDevice.Used | Use a trusted device to fulfill sign-in MFA |

## SAML application \{#saml-application}

Expand Down
9 changes: 9 additions & 0 deletions docs/developers/webhooks/events.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,15 @@ This guide list the different Logto webhook events and explains when each event
| OrganizationScope.Deleted | A organization permission is deleted. |
| OrganizationScope.Data.Updated | A organization permission's data is updated, e.g., organization permission description. |

### Trusted device \{#trusted-device}

| Event type | Description |
| --------------------- | --------------------------------------------------------------------------------- |
| TrustedDevice.Created | A trusted-device record is created after a successful authentication interaction. |
| TrustedDevice.Deleted | A user or administrator removes a trusted-device record. |

Natural expiration does not emit a `TrustedDevice.Expired` webhook because expiration is a time-based validity change rather than an application mutation. The `TrustedDevice.Created` payload includes `expiresAt` so consumers can derive the expected expiration time. Successful use and trusted-device policy changes do not emit lifecycle webhooks.

### Management API triggered events \{#management-api-triggered-events}

| API endpoint | Event |
Expand Down
2 changes: 1 addition & 1 deletion docs/end-user-flows/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ End-user flows cover all verification processes for user interactions, categoriz
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Sign-up and sign-in](/end-user-flows/sign-up-and-sign-in) | <ul><li>[Email / phone / username sign-up](/end-user-flows/sign-up-and-sign-in/sign-up)</li><li>[Email / phone / username sign-in](/end-user-flows/sign-up-and-sign-in/sign-in)</li><li>[Social login](/end-user-flows/sign-up-and-sign-in/social-sign-in)</li><li>[Passkey sign-in](/end-user-flows/sign-up-and-sign-in/passkey-sign-in)</li><li>[Reset password](/end-user-flows/sign-up-and-sign-in/reset-password)</li><li>[Terms & Privacy](/end-user-flows/sign-up-and-sign-in/terms-and-privacy)</li><li>[Disable user registration](/end-user-flows/sign-up-and-sign-in/disable-user-registration)</li></ul> |
| [Enterprise SSO](/end-user-flows/enterprise-sso) | <ul><li>[SP-initiated SSO](/end-user-flows/enterprise-sso/sp-initiated-sso)</li><li>[IdP-initiated SSO](/end-user-flows/enterprise-sso/idp-initiated-sso)</li></ul> |
| [Multi-factor authentication](/end-user-flows/mfa) | <ul><li>[Authenticator apps OTP](/end-user-flows/mfa/authenticator-app-otp)</li><li>[Passkeys (WebAuthn)](/end-user-flows/mfa/webauthn)</li><li>[Backup codes](/end-user-flows/mfa/backup-codes)</li></ul> |
| [Multi-factor authentication](/end-user-flows/mfa) | <ul><li>[Authenticator apps OTP](/end-user-flows/mfa/authenticator-app-otp)</li><li>[Passkeys (WebAuthn)](/end-user-flows/mfa/webauthn)</li><li>[Backup codes](/end-user-flows/mfa/backup-codes)</li><li>[Trusted devices](/end-user-flows/mfa/trusted-devices)</li></ul> |
| [Authentication parameters](/end-user-flows/authentication-parameters) | <ul><li>[First screen](/end-user-flows/authentication-parameters/first-screen)</li><li>[Direct sign-in](/end-user-flows/authentication-parameters/direct-sign-in)</li></ul> |
| [Magic link (One-time token)](/end-user-flows/one-time-token) | <ul><li>Organization member invitation</li><li>User invitation when registration is disabled</li><li>Sign in or sign up using magic link</li></ul> |
| Authorize third-party apps | <ul><li>[Consent screen for OIDC / OAuth apps](/end-user-flows/consent-screen)</li></ul> |
Expand Down
1 change: 1 addition & 0 deletions docs/end-user-flows/account-settings/by-account-center-ui.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,3 +232,4 @@ If you need more customization beyond what the prebuilt UI and custom CSS offer,
- [Account settings by Account API](/end-user-flows/account-settings/by-account-api) - Build custom account management with full API control
- [Account settings by Management API](/end-user-flows/account-settings/by-management-api) - Admin-level account management
- [MFA configuration](/end-user-flows/mfa) - Set up multi-factor authentication
- [MFA trusted devices](/end-user-flows/mfa/trusted-devices) - Configure and manage time-limited browser trust
4 changes: 4 additions & 0 deletions docs/end-user-flows/mfa/README.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,3 +42,7 @@ Logto simplifies the MFA activation process with a one-click toggle, removing th
- [SMS verification](/end-user-flows/mfa/sms-mfa): Use SMS messages to send one-time codes (verification codes) for authentication.
- [Email verification](/end-user-flows/mfa/email-mfa): Use email messages to send one-time codes (verification codes) for authentication.
- [Backup codes](/end-user-flows/mfa/backup-codes): Generate one-time-use backup codes for emergency access.

**Related MFA capabilities**:

- [Trusted devices](/end-user-flows/mfa/trusted-devices): Let users skip repeated MFA prompts on a trusted browser with a time-limited, revocable credential. Users opt in on a separate **Trust this device** page at the end of an eligible sign-in or sign-up flow.
Loading
Loading