@bryan-robinson

I'm getting the 4503 even though I'm running the caller and FusionAuth on localhost for dev testing purposes. The caller is on localhost:8080 and FA is on localhost:9011.

According to the documentation for app/refresh, this should work.

Any ideas?

@bryan-robinson

We are not using DPoP at all, and the app/me call is being made transparently by the FusionAuth Vue SDK, so is not something we can change. That is the default when setting up the VueJS SDK.

I've isolated this to the upgrade to 1.60.0. It has the issue. 1.59.1 works fine.

I suspect it's due to the new tty claim that is included in the at and idt tokens, which did not exist before.

The external JWT reconcile API only returns at and rt tokens. It does not return an idt. So we were setting the at value for the idt cookie. But now that the two tokens can be differentiated, I suspect that this causes the issue.

Was trying to use the Hosted Backend app/refresh API to get refreshed tokens, including an idt, but that is returning a 403-Forbidden for some reason. Documentation on what is required for that API call is rather sparse Says it needs the app.rt cookie, which we have set...but seems it needs more.

Load testing FusionAuth typically involves using a modern tool like k6 to simulate your expected traffic patterns. Here's the general approach:

Use k6 or other HTTP-capable load testing tools: While k6 is a good modern option, FusionAuth can be load tested with any HTTP-capable load testing tool such as Gatling, JMeter, or Locust. FusionAuth also provides an open source load testing repository with pre-built scenarios including creating tenants and applications, registering users, logging users in via the Login API, and full Authorization Code grant flows.

Profile your traffic: Use your load testing tool to determine what your actual traffic patterns will look like, especially accounting for your spiky demand. This helps you understand the load FusionAuth will need to handle. Look beyond just averages—also check the p95 (95th percentile) response time to understand the experience of your slowest users.

Test in a production-like environment: It's critical to load test against an environment that mirrors your expected production setup. If you're using FusionAuth Cloud, the Basic Cloud tier (single node running FusionAuth, Elasticsearch, and PostgreSQL together) is not representative and not recommended for load testing. Instead, use a Business Cloud or High-Availability plan for meaningful load testing. You can spin up an HA instance, run your tests, and tear it down—you'll only be charged for the time it's running.

Notify FusionAuth if testing on Cloud: If you're load testing on FusionAuth Cloud, open a support ticket to let the team know when you plan to stress test, as they monitor CPU and other metrics.

Monitor the right components: Performance bottlenecks are typically the database or CPU nodes. Both logins and user creation are CPU-intensive due to password hashing. If testing a multi-node system behind a load balancer, disable sticky sessions as they are not required for FusionAuth.

IP allowlisting considerations: If you're using FusionAuth Cloud, you may need to consider IP allowlisting depending on your security configuration. FusionAuth Cloud has protections in place to prevent DoS attacks and keep services running smoothly.

The specific approach can vary based on your exact traffic patterns and requirements, but these are the key components most customers use when load testing FusionAuth.

Related Documentation Load Test Documentation - Comprehensive guide on load testing FusionAuth, including tool recommendations and best practices FusionAuth Load Tests GitHub Repository - Open source load testing scripts with pre-built scenarios Handling Spiky Game Traffic: Registration & Autoscaling Best Practices - Specific guidance for handling spiky traffic patterns during high-demand scenarios FusionAuth Cloud High Availability Architecture - Details on HA deployment options for production-like testing FusionAuth Cloud Security - Information about Cloud security protections and rate limiting Troubleshooting Performance - Guide for troubleshooting performance issues Scaling Your Auth - Best Practices for Performance and Security - General guidance on scaling authentication systems

Yes, you can use your FusionAuth licenses across multiple environments, but you should use the appropriate license type for each:

License Structure

In your account portal at account.fusionauth.io, you should see two licenses:

Production License — use this for your production environment only Non-Production License — use this for your dev and staging environments Best Practice Deploy the Non-Production license to your dev and staging instances Deploy the Production license to your production instance

Both licenses can be active simultaneously across different deployments without conflict. The license key itself is tied to your account and does not interfere with your managed FusionAuth Cloud setup when used in self-hosted deployments.

Important Notes

The non-production license can be used across as many non-production environments as you need — dev, staging, QA, UAT, CI/CD, or even individual developer local instances. There's no limit on the number of instances using the non-production key.

Do not use the production license on non-production environments — this would cause test logins to count toward your Monthly Active Users (MAU) and affect your billing.

License costs are not based on the number of instances — whether you have 1, 2, or 100 instances, the license cost is related only to your plan tier and MAU count.

Using self-hosted licenses won't affect your FusionAuth Cloud deployment — the licenses operate independently, so activating your license keys on self-hosted instances will not disrupt your existing managed environment.

Related Documentation Licensing Documentation — Overview of FusionAuth licensing concepts License FAQ: Non-Production Licenses — Details on using licenses for dev/QA/UAT servers License FAQ: Multiple Deployments — How license costs work with multiple instances Account Portal Documentation — Where to find your license keys Cloud vs Self-Hosted — Comparison of hosting options

The act claim was reserved in FusionAuth 1.70.0 because it is defined in RFC 8693 (OAuth 2.0 Token Exchange) as a standard claim representing the "actor" in delegated token scenarios. FusionAuth began enforcing this reservation to ensure compliance with the RFC and prevent conflicts with the claim's intended usage in token exchange flows.

Why This Is Classified as Minor

FusionAuth follows semantic versioning, and this change was classified as minor rather than breaking because:

The act claim is a standardized RFC claim with a specific defined purpose Using non-standard values in RFC-defined claims can cause interoperability issues with other OAuth/OIDC systems The change aligns FusionAuth's behavior with industry standards

However, the lack of logging when a reserved claim is silently discarded is a valid concern and makes troubleshooting difficult.

Recommended Solutions 1. Use a Custom Claim Namespace

Instead of using act directly, use a namespaced custom claim that won't conflict with RFC-defined claims:

// In your JWT populate lambda jwt['https://yourapp.com/actor'] = 'your-actor-id';

This approach is standard practice in OAuth/OIDC and prevents future collisions with reserved claims.

2. Use applicationId or Other Non-Reserved Claims

If the actor represents an application or service account, consider using the built-in applicationId claim or another custom claim that describes your specific use case (e.g., actorId, serviceAccountId).

Why Reserved Claims Cannot Be Overridden

Reserved claims like act, sub, iss, aud, etc., are protected because they have specific meanings defined by RFCs and must maintain consistent behavior for:

Interoperability: Other systems expect these claims to have specific formats and meanings Security: Claims like iss and aud are critical for token validation and cannot be arbitrarily changed Standards Compliance: FusionAuth aims to be a standards-compliant identity provider Migration Path

If you're currently using act in production:

Update your JWT populate lambda to use a namespaced custom claim Update your application to read from the new claim name Test thoroughly in a non-production environment before upgrading

If you need to maintain backward compatibility during migration, you could temporarily set both claims in your lambda (the custom namespaced one and attempt to set act, knowing it will be discarded) and update your application to check for both, prioritizing the custom claim.

Related Documentation JWT Populate Lambda - Documentation on customizing JWT claims with lambdas Client Credentials JWT Populate Lambda - Documentation for lambdas in the Client Credentials grant OAuth Token Exchange (RFC 8693) - FusionAuth's implementation of RFC 8693, which defines the act claim FusionAuth 1.70.0 Release Notes - Release notes for version 1.70.0 FusionAuth 1.70 Announcement: Token Exchange - Blog post explaining the new token exchange feature and scoped delegation GitHub Issue #1721: JWT claim overriding, namespacing or the ability to unreserve claims - Open issue discussing the ability to override or unreserve claims Additional Context on Reserved Claims

As of FusionAuth 1.70.0, the following claims are reserved in JWT Populate Lambdas and cannot be modified:

act (added in 1.70.0) amr auth_time authenticationType cnf fa_uid gty iat sub tid tty

Note: The exp claim can be lowered (shortened) but not extended or removed.

For other lambda types (Client Credentials, UserInfo, Token Exchange), different sets of reserved claims apply. Always use namespaced custom claims (e.g., https://example.com/my-claim) to avoid conflicts with current or future reserved claims.

Unfortunately, lambdas won't help here. FusionAuth never exposes the password anywhere lambda code can access it, so you can't write a lambda that validates complexity.

You do have several other options, each with tradeoffs:

Low complexity for everyone, with MFA for franchise managers. Configure the tenant with low complexity rules and require MFA for the franchise manager group using the MFA lambda. The MFA lambda can be combined with most of the other options below.

Low complexity for everyone, with an IdP for franchise managers. Add an identity provider pointing to a different FusionAuth instance/tenant or a corporate directory, and have franchise managers authenticate there.

The FusionAuth instance can have more complex password requirements. Add a Login Validation lambda that denies login for users in the franchise manager group unless they authenticated through that IdP. Modify the theme to hide the IdP button on the normal login page. Pass an idp_hint on the authorization URL for everyone in the franchise manager group.

Passwordless for restaurant staff. Let restaurant staff log in without a password and set higher complexity rules at the tenant level for everyone else.

Two tenants with separate applications. Create tenant A (low complexity) and tenant B (high complexity). Have the restaurant staff application use tenant A's ID and the franchise manager application use tenant B's ID. You could also use a universal application to represent the application.

Two tenants with a connector. Again, tenant A is low complexity and tenant B is high complexity.

Set up a connector from tenant B to tenant A, with MFA lambda rules in tenant B for franchise managers. Configure the connector to not migrate users. Have all users log in to the application in tenant B, which checks tenant A for restaurant staff.

All of these will work, but they have tradeoffs. Some may increase your MAU count, and some may add latency.

Why not per-application password rules?

As an aside, I don't expect FusionAuth to ever support different password rules per application, because it would lead to confusing user experiences:

If the staff app requires 10 characters and the manager app requires 15, and a user registers in the staff app, what happens if/when they log in to the manager app? Do we deny the login? Force a password change? If the staff app requires 10 to 20 characters and the manager app requires 25 to 35, no single password can satisfy both. Would a user have to change their password every time they switch between the two apps? Can you migrate users between applications?

This is a confirmed bug in FusionAuth 1.69.2. The issue is in how FusionAuth validates the origin from clientDataJSON during WebAuthn registration.

This has been fixed and will be released in the next release. Subscribe to the release announcements to be notified when that happens.

The data sub-object containing auth_time and authentication_type in refresh token metadata is not currently a documented or officially supported feature in FusionAuth. Its presence is inconsistent across authentication flows, as you've observed — it appears for some authentication types but not others (notably absent for MFA + PASSWORD flows).

According to the official documentation, the only documented fields within refresh token metaData are:

metaData.device — An object containing device information (name, type, description, lastAccessedAddress, lastAccessedInstant) metaData.scopes — An array of OAuth scopes associated with the token metaData.resources — An array of resource URIs per RFC 8707 (available since v1.67.0)

The data sub-object with auth_time and authentication_type that you're observing is not part of the documented API contract. Because this is undocumented behavior, you should not rely on it in production code, as it may change or be removed in future versions without notice.

Important Distinction: auth_time on JWTs vs Refresh Tokens

Note that auth_time is a standard and documented claim on access tokens and ID tokens (the JWTs themselves), where it represents the time of initial authentication. However, it is not a documented field on the refresh token record itself when queried via the retrieval API.

Related Documentation Retrieve Refresh Tokens API — Official API documentation including the complete response body structure for refresh tokens Access Token and ID Token Claims — Where auth_time is officially documented as a JWT claim Multi-Factor Authentication (MFA) — Guide to implementing MFA in FusionAuth JWT Refresh API — How to use refresh tokens to obtain new access tokens

For FusionAuth Cloud (SaaS) instances, database migrations are automatically applied as part of the upgrade process. You do not need to take any action.

The FusionAuth Cloud team handles all required database migrations when upgrading your hosted instance to a new version. This is managed on your behalf as part of the cloud service. When you initiate an upgrade through your FusionAuth Account dashboard, the migrations run automatically during the upgrade process.

For HA Cloud (multi-node) deployments, nodes are upgraded one at a time. When the first upgraded node connects to the database, it locks the database and runs the required migrations while other nodes continue serving traffic, resulting in only seconds of downtime.

For Basic/Business Cloud (single-node) deployments, the entire instance goes offline during the upgrade, with downtime ranging from 5 to 60 minutes depending on the amount of data and schema changes required.

If you are running a self-hosted FusionAuth instance, you would need to follow the upgrade guide and apply any required out-of-band migrations manually (or configure Silent Mode for automatic migrations). However, for cloud-hosted instances, this is handled automatically by FusionAuth.

Note: You cannot downgrade a FusionAuth Cloud deployment version after upgrading, so it's recommended to test upgrades in a non-production environment first if possible.

Related Documentation FusionAuth Cloud - Upgrading a Deployment - Details on the Cloud upgrade process and downtime expectations Upgrade FusionAuth - Upgrade Options - Overview of different upgrade strategies including HA deployments Out-of-Band Database Upgrades - Information on manual migrations for self-hosted instances Silent Mode - Automatic migration handling for self-hosted deployments

To migrate a user from Microsoft Authenticator to 1Password (or any other TOTP authenticator app), the recommended approach is to remove the old method first, then have the user re-enroll with the new app.

Step 1: Prompt the user to enroll with 1Password

The user can add a new authenticator method via:

Self-service account management (paid plans):

User navigates to their account page → Manage two-factor → Add two-factor → Authenticator app Scan the new QR code with 1Password, including providing a name See: Add Authenticator as a second factor

You can also build your own page using the APIs.

This approach ensures a clean transition between authenticator apps without conflicts or confusion.

Step 2: Remove the existing Microsoft Authenticator method

You have two options:

Option A: Admin UI

Navigate to Users → [Select User] → Multi-Factor tab Click the red trash icon to remove the authenticator method An admin role can do this without requiring a one-time code from the user An mfa_deleter role can do this, but confirmation from the user is required. See: Disable MFA documentation

Option B: User API (programmatically)

GET the user object Remove the authenticator entry from the twoFactor.methods array PUT the updated user object back This requires no code from the user and is useful for support scenarios (e.g., user lost their device) Note: Use PUT rather than PATCH due to how arrays are handled in the API

This approach ensures that the user always has MFA enabled, but requires action on their part.

If you reverse them, but use an MFA policy of Required (or one of the intelligent MFA policies), then users will be forced to re-enroll.

Related Documentation Multi-Factor Authentication (MFA) Overview Disable MFA on a User Add Authenticator as a Second Factor Self-Service Account Management Update a User API Disable Multi-Factor API

Currently, there is no sorting logic implemented for deployments in the FusionAuth Cloud account portal. The order of deployments is not sorted alphabetically or by any other consistent criteria at this time.

This has been noted as a feature request to add sorting capabilities (or the ability to manually sort) deployments in the account portal. This would help prevent accidental selection of the wrong instance when managing multiple FusionAuth Cloud deployments.

In the meantime, extra care should be taken when selecting deployments from the list to ensure you're working with the correct instance. You can use the Rename feature (available in the Action dropdown menu for each deployment) to give your deployments descriptive names that help distinguish between different products or environments.

Related Documentation Managing Your Deployments - Overview of managing FusionAuth Cloud deployments in the account portal The Account Portal - Documentation on accessing and using the account portal FusionAuth Account Portal Reference - Complete reference for the FusionAuth account portal features

FusionAuth Cloud deployments can provide static outbound IP addresses for email delivery and other outbound connections. The availability and process depend on when your deployment was created.

Getting Static IP Addresses

For new FusionAuth Cloud deployments: Static IP addresses are already configured automatically.

For existing deployments: You need to open a support ticket to get static IP addresses assigned.

How to Request Your Deployment's IP Addresses

To retrieve the specific outbound IP addresses for your deployment (e.g., to allowlist them with your SMTP provider):

Open a support ticket Include the name of the deployment for which you need the outbound IP addresses

Once assigned, these IP addresses will remain static and won't change during upgrades, restarts, or normal operations.

Important Notes About the IP Addresses The provided IP addresses are for outbound traffic only (firewalls, allowlists, SPF records, etc.) — they will not respond to HTTP API calls You should add these IPs to your SPF DNS record for your sending domain to prevent password reset and other transactional emails from landing in spam Multiple IP addresses may be provided for high availability Recommended Approach

If you have both production and development environments:

Request and configure the static IPs for your development instance first Test email delivery with the allowlisted IPs Once verified, request and configure the production deployment's static IPs Related Documentation FusionAuth Cloud - Deployment IP Addresses - Official documentation on obtaining IP addresses for your FusionAuth Cloud deployment Configure SMTP - Complete guide to configuring email delivery in FusionAuth SMTP Best Practices - Recommendations for maintaining good sender reputation including SPF records GitHub Issue #1393 - Original feature request for static IP addresses in FusionAuth Cloud

The behavior you're experiencing is likely related to the SSO Session Timeout setting in your Tenant configuration.

Understanding the "Remember Me" Checkbox

The "Remember Me" checkbox (labeled "Keep me signed in" in the default theme) controls the FusionAuth SSO session. When checked, it creates a persistent cookie that allows users to remain logged in across browser sessions. However, even with this option checked, the session will still expire based on your configured Session Timeout value.

Check Your SSO Session Timeout

Navigate to:

Tenants → (your tenant) → OAuth tab Look for the Session timeout setting The default value is 3600 seconds (1 hour)

This setting controls how long the FusionAuth SSO session remains valid. When this duration expires, users are logged out and must re-authenticate, even if they previously selected "Remember Me."

The one-hour expiration you're seeing matches the default Session Timeout setting, which explains why users are consistently logged out after that time period.

To Resolve This Issue Increase the Session timeout value to a longer period (e.g., 86400 seconds for 24 hours, 2592000 seconds for 30 days, or whatever suits your security requirements) Save the Tenant configuration Have users log in again with "Remember Me" checked

The new timeout will apply to all new SSO sessions created after the configuration change.

Related Documentation Logout and Session Management - SSO Session Timeouts FusionAuth Cookies Reference Does FusionAuth support Remember Me functionality? Configure Session Timeout

Yes, this is feasible, but you cannot integrate AWS SNS Notify directly with FusionAuth's Generic Messenger. You'll need to implement a middleware relay to bridge the two systems.

Architecture

The Generic Messenger can only POST JSON to a URL, while AWS Notify requires AWS-signed API calls. The solution is to place a relay service between FusionAuth and AWS SNS.

Recommended approach:

Set up an AWS API Gateway endpoint backed by a Lambda function as your relay Configure FusionAuth's Generic Messenger to POST to this API Gateway endpoint The Lambda function receives the phone number and message from FusionAuth The Lambda extracts the MFA code from the payload The Lambda calls AWS SNS SendNotifyTextMessage with the code as a template variable AWS SNS delivers the SMS using your pre-approved template Important constraint

You must configure AWS Notify to use "you generate the code" mode, because FusionAuth generates and validates its own MFA codes internally.

Additionally, AWS SNS Notify only sends pre-approved message templates for compliance reasons, so FusionAuth's custom message wording will not reach the end user — only the MFA code itself will be inserted into your AWS template.

Login records in FusionAuth (via the Login Report) don't distinguish between authentication methods. The response fields include applicationId, applicationName, loginId, loginIdType, instant, ipAddress, and userId, but none indicate the credential type used (token vs. password vs. SSO).

Recommended Approach

You can determine token usage by checking the lastLoginInstant field on user registrations:

Use the Retrieve User Registration endpoint (GET /api/user/registration/{userId}/{applicationId}) or search for users with tokens For each registration with an authenticationToken, check the lastLoginInstant against your time windows (30 days, 90 days, 1 year) If lastLoginInstant falls within your time window for any user, someone authenticated to that application during that period

Here's a Python script approach:

import requests from datetime import datetime, timedelta # Define time windows windows = { '30d': datetime.now() - timedelta(days=30), '90d': datetime.now() - timedelta(days=90), '1y': datetime.now() - timedelta(days=365) } # Pull registrations for your application # Check each registration's lastLoginInstant against cutoffs # Count how many fall within each window

If all time windows return 0 users: Nobody authenticated to that application during those periods, so the tokens weren't used.

If users show up: The lastLoginInstant can't distinguish whether they used the token, password, or SSO. In this case, you have two additional options:

Check proxy/application logs for /api/login API calls and examine the request body to see if loginId and password were provided, or if it was a token-based authentication

Check webhook events: If you have webhooks configured, examine user.login.success events for the authenticationType field. When a user authenticates with an application authentication token, the value will be APPLICATION_TOKEN. Other possible values include PASSWORD, REFRESH_TOKEN, identity providers like GOOGLE or FACEBOOK, and many more.

Check JWTs: If you capture or log JWTs, the access token contains an authenticationType claim that indicates the authentication method used. For authentication tokens, this will be set to APPLICATION_TOKEN.

Related Documentation Application Authentication Tokens - Overview of application authentication tokens and how they work Retrieve a User Registration API - API documentation for retrieving user registration details including authenticationToken and lastLoginInstant Search Login Records API - API for searching login records (note: does not include authenticationType) User Login Success Event - Webhook event that includes authenticationType field Authentication Types Reference - Complete list of authentication types including APPLICATION_TOKEN, PASSWORD, and others Login API - API for authenticating users with various methods including authentication tokens

For modeling an OAuth2 system in FusionAuth, here are the key architectural considerations:

Tenants Use separate tenants when you need complete isolation between environments (e.g., different customers in a multi-tenant SaaS product, or separate production/staging environments with distinct user bases) Use a single tenant when your users and applications share the same authentication realm Tenants provide the highest level of separation — each has its own users, applications, groups, and configuration Entities and Entity Types Entity Types define categories of non-user objects in your system (e.g., "Device", "API Client", "Organization", "Service Account") Entities are instances of those types (e.g., a specific device, a specific organization) Use entities to represent OAuth2 concepts like: Client credentials for machine-to-machine authentication Devices in device authorization flows Organizations or business units that own applications Non-human actors that need permissions or relationships to users Common Pattern

A typical OAuth2 architecture in FusionAuth might look like:

Tenant = Your authentication realm/environment Applications = Your OAuth2 clients (registered apps that can authenticate users) Entity Types = Categories like "Organization", "Device", or "API Client" Entities = Specific instances (e.g., "Acme Corp" as an Organization entity) Users = End users who authenticate

The key is mapping your OAuth2 concepts to FusionAuth's primitives based on whether they represent users (User objects), applications (Application objects), or other non-user actors/resources (Entities).

Finding Users with Email MFA Configured

You can search for users with email MFA using the query string pattern in either the Admin UI search bar or via the Search API:

twoFactor.methods.method:email

This follows the same pattern used for searching users by any MFA method.

Getting an Accurate Count Efficiently

To get a count without retrieving all user records, use the Search API with accurateTotal enabled and a minimal numberOfResults:

{ "search": { "accurateTotal": true, "queryString": "twoFactor.methods.method:email", "numberOfResults": 1, "startRow": 0 } }

The response will include a total field containing the exact count of matching users.

Last-Used MFA Information

Unfortunately, FusionAuth does not store a timestamp for when a user last used their MFA method. However, each MFA method object includes a lastUsed boolean field at users[x].twoFactor.methods[x].lastUsed that indicates which method was most recently used by that user. This is a boolean flag rather than a timestamp, so you can identify which method was used last but not when it was used.

Hi @david-kircheis,

The cross-platform authenticator passkey functionality is not available for the licensed community edition, only the platform passkey functionality.

The options I see for your use case are:

talk to sales about an enterprise license, if it fits your business model. We do offer non-profit discounts in certain circumstances. use platform authenticators with all their limits move to a different identity provider

While we'd love to have FusionAuth used by everyone, we can't offer all features to every plan level. We recognize this limit means FusionAuth isn't the right solution for every authentication problem.

I appreciate you using FusionAuth now and hope it remains helpful to you.

Unfortunately, there is no built-in way to customize the 404 page via FusionAuth themes to force a redirect. The standard theme editor does not include a template for the 404 error page, and this functionality is not currently supported.

The recommended approach is to:

Investigate the root cause: Try to determine what circumstances are causing users to hit the 404 page. If you can replicate the issue, identifying the source will help prevent it from occurring.

Use a reverse proxy: If you need to redirect users away from the 404 page, the recommended solution is to set up a reverse proxy (such as nginx, Apache, or similar) in front of FusionAuth that can intercept 404 responses and redirect users to an appropriate page. For example, with nginx, you can use the proxy_intercept_errors directive to handle error responses.

It's generally better to address why users are reaching the 404 page rather than simply redirecting them away from it, as this may indicate an underlying issue with URL construction, deep linking, or session handling in your application.

Related Documentation Themes Overview - Learn about FusionAuth's theme customization capabilities Troubleshooting Proxies - Important guidance when using FusionAuth behind a reverse proxy 404 Page Theme Forum Discussion - Community discussion confirming this limitation GitHub Issue #404 - Feature request for customizable error pages (consider upvoting if this is important to you)

This issue is related to Gmail's safe-links protection feature, which scans links in emails for security purposes.

Root Cause

When Gmail scans the password reset button/link, it fires two GET requests to the /password/change endpoint:

One request from Gmail's link scanner One request from the actual user click

Each request triggers the MFA code generation, resulting in two codes being sent.

Why FusionAuth's Normal Protections May Not Apply

FusionAuth has built-in protections against email link scanners consuming codes or triggering duplicate actions. Starting with version 1.49.0, FusionAuth introduced a mandatory confirmation page that requires user interaction when a link request doesn't originate from the same browser that initiated the workflow. This prevents most link scanners (including aggressive ones like Outlook Safe Links) from consuming codes.

However, this protection may not engage if:

Custom theme is missing the confirmation template — If you're using a custom theme, you need to copy the "Confirmation required" template (/confirmation-required) into your theme to benefit from this feature. Without it, the protection doesn't work. The user recently changed their password and has "confirmation trust" already established in their browser A proxy between the client and FusionAuth is not properly handling cookies that prevent link checker issues The state parameter is being mangled in a custom theme, causing unexpected behavior Solutions

Add the Confirmation Required Template to Your Custom Theme — This is likely the primary fix. The confirmation required template was added in version 1.49.0 and must be manually added to custom themes. Copy it from the default theme to ensure link scanners are blocked from triggering duplicate MFA codes.

Upgrade to the Latest Version of FusionAuth, which includes the most recent fixes for link scanner issues

Review Custom Theme Modifications — Compare your theme files against the stock FusionAuth theme to ensure the state parameter and form structure haven't been altered in ways that bypass protections

Check Proxy Configuration — Ensure any proxy in front of FusionAuth is correctly forwarding cookies and not causing duplicate page renders

Test with Default Theme — Verify the issue doesn't occur with default templates to isolate whether customizations are the cause (you've already confirmed this resolves the issue)

Why Subsequent Attempts Work

After the first password reset attempt, browser state and cookies are properly established, preventing the duplicate request issue on subsequent attempts from the same session.

Why Button vs Link Matters

The difference between button and link behavior may be related to how your custom theme implements these elements. Buttons might use different form submission methods or lack the postMethod=true parameter that converts GET requests to POST requests (which link scanners typically don't replicate).

Related Documentation Confirmation Required Template Variables — Details on the confirmation required template introduced in version 1.49.0 Email Link Workflow Improvements (FusionAuth 1.49) — Explains the confirmation page feature designed to prevent link scanners from consuming codes FusionAuth Cookies Reference — Information about cookies used by FusionAuth's hosted login pages GitHub Issue #2253: Email MFA codes sent multiple times during password resets — Related issue about duplicate MFA codes Community Discussion: Password Reset Expired Link - Safelinks Users — Discussion about link checker issues with password reset flows