Usage
What sign-in looks like, the password fallback, and per-user admin actions.
End-user sign-in flow
The sign-in card has a small state machine. A visitor moves through whichever path matches their device and preference.
State A: email entry
The default state. The visitor types their email address. The Send Link button stays disabled until the email is syntactically valid.
On submit, MagicAuth always returns the same opaque envelope ("If an account exists, we sent a sign-in link") so probing bots cannot tell registered emails apart from unregistered ones.
State B: code entry
Immediately after submitting state A, the form transitions to state B and a top-right toast confirms "Email sent. Check your mail app." The card now shows a 6-character code input.
The visitor can either:
- Click the link in the email. Works on any device. Multi-use within the TTL.
- Type the code (
XXX-XXX) into the field on the original device. Single-use; burns on the first successful submission.
State C: password fallback
A "Sign in with password" link is always visible (unless turned off in settings). Clicking it reveals an inline username and password field inside the same MagicAuth shell, with no bounce to native wp-login.php. Successful authentication redirects to the same destination as the magic-link path.
State D: lost password
From state C, "Lost your password?" reveals an email field. The submit handler always returns the same opaque envelope, regardless of whether the user matched, the email sent, or a throttle fired. This closes the user-enumeration oracle that WordPress's default retrieve_password() leaves open.
State E: reset password
The reset link in WP's standard recovery email lands in the branded MagicAuth shell instead of the default wp-login.php reset form. Invalid or expired keys bounce back to state D with a friendly toast.
The email
The sign-in email is a single multipart message.
Structure
- Subject.
XXX-XXX is your {Company}-code. The code appears in inbox previews and lock-screen notifications. - HTML body. Logo at the top, a brand-colored Sign in button, the code displayed prominently below, and an expiry note.
- Plaintext body. Included as
AltBodyso plaintext-only mail clients render the link and code without HTML.
Customisation
Templates and filters cover every part of the email. See Developers / Email customisation.
Multi-use links
A magic link is multi-use within its TTL. Default is 2 uses.
Why two
Some inbox providers and security gateways prefetch URLs to scan them for malware. The prefetch counts as use 1. With the default max_link_uses = 2, the user's actual click counts as use 2 and still works. The (N+1)th click returns the generic error.
Codes are different
Codes are always single-use. They burn on the first successful submission, or after 5 wrong attempts on the same row.
Recovery: never get locked out
Three independent layers, in order of effort.
1. The password link
Visible on every sign-in card unless explicitly turned off in settings. Reveals MagicAuth's branded password screen.
2. ?magicauth=off
Append this to your wp-login.php URL:
https://example.com/wp-login.php?magicauth=offSets a cookie scoped to /wp-login.php that disables the branded login replacement for your browser only. The default WordPress login form appears in its place. Other users continue to see the MagicAuth screen.
3. MAGICAUTH_DISABLE constant
Add to wp-config.php:
define( 'MAGICAUTH_DISABLE', true );The plugin skips its Plugin::boot() entirely. Requires file-system access (FTP, SSH, hosting panel).
Per-user admin actions
On any Users → All Users → user edit screen, MagicAuth adds a section with these tools (admin-only, manage_options-gated AJAX).
Issue a magic link
Generates a one-time link and copies it to your clipboard. Useful for hand-delivering access in chat or 1Password.
Send the user a magic link
Renders and sends the standard email to that user, on demand.
Reset all outstanding tokens for this user
Invalidates every unconsumed link and code that user holds. Useful after a suspected compromise of a single account.
Disable magic-link sign-in for this user
Flips a magicauth_disabled user-meta flag. The user can still sign in with their password (assuming the password link is enabled). On the next sign-in attempt, that user receives a one-shot disabled-notice email explaining the change.
The disabled-notice email is throttled to one per 24 hours per email so the request form cannot be weaponised to flood a disabled user's inbox.
Programmatic sign-in
Third-party code (a WooCommerce post-purchase hook, a membership plugin onboarding flow, a custom CLI script) can issue and send magic links without going through the form. See Developers / Programmatic API.