This is going to vary based on your publishing system, but you can use FusionAuth's OIDC prompt=none to see if users have an active SSO session.

If the user has checked remember me and has logged in within the tenant session timeout, the request will succeed, otherwise it will fail.

Step 1: Main Page

This creates the iframe and listens for the result.

On your main page, create the hidden iframe targeting FusionAuth with prompt=none. You also listen for a message event from the iframe to know whether to display or hide the CTA <div>, which needs the id trial-cta:

// 1. Listen for the result sent back from the iframe callback page window.addEventListener('message', (event) => { // Verify the origin matches your application domain for security if (event.origin !== window.location.origin) { return; } const ctaDiv = document.getElementById('trial-cta'); if (event.data && event.data.type === 'SILENT_AUTH_RESPONSE') { if (event.data.status === 'authenticated') { // User has an active SSO session; keep CTA hidden if (ctaDiv) { ctaDiv.style.display = 'none'; } } else if (event.data.status === 'login_required') { // User is not authenticated; show the trial CTA popup/div if (ctaDiv) { ctaDiv.style.display = 'block'; } } } }); // 2. Create the hidden iframe to initiate the prompt=none request const iframe = document.createElement('iframe'); iframe.style.display = 'none'; iframe.src = 'https://<your-fusionauth-instance>/oauth2/authorize?' + 'client_id=<YOUR_CLIENT_ID>&' + 'response_type=code&' + 'redirect_uri=https://<your-app-domain>/silent-callback.html&' + 'scope=openid&' + 'prompt=none&' + 'state=<YOUR_STATE>'; document.body.appendChild(iframe); Step 2: Callback Page

Configure this page as an authorized redirect URI in your FusionAuth application [Request Parameters].

When FusionAuth redirects back with the authorization code code or error=login_required, this page parses the URL and communicates back to the parent window:

// Parse query parameters from the redirect URI const params = new URLSearchParams(window.location.search); const code = params.get('code'); const error = params.get('error'); if (code) { // Session exists: notify the parent window window.parent.postMessage({ type: 'SILENT_AUTH_RESPONSE', status: 'authenticated', code: code }, window.location.origin); } else if (error === 'login_required') { // No active session: notify the parent window to show CTA window.parent.postMessage({ type: 'SILENT_AUTH_RESPONSE', status: 'login_required' }, window.location.origin); } Cautions And Additional Considerations

This won't work across all browsers, especially those with privacy features or if your FusionAuth instance isn't on the same root domain as the application. More details here.

Test the scenarios you need to support.

The CTA should include information about how to sign up or log in if the user already has an account.

You may want to add server or client side logic to obfuscate the page contents.

This is expected behavior for certain authentication flows in FusionAuth. When authentication happens via methods like refresh token grants, SSO handoffs, or silent authentication (where the user already has an active session), the event may not include an applicationId because the authentication isn't directly tied to a specific application registration at that moment.

Workarounds and Best Practices 1. Check the JWT for Application Context

Your applications should be validating the JWT claims after authentication, including:

applicationId (or aud claim) — identifies which application the token was issued for Other application-specific claims

See JWT Components Explained for details on these claims.

2. Enable Automatic Registration on Proxy Applications

If you're using a proxy or gateway application that performs authentication on behalf of other applications, enable automatic registration for that proxy application. This ensures users are properly registered to the proxy app, which can help maintain application context.

Refer to the Application Suite edge cases documentation for scenarios where this pattern is useful.

3. Alternative Event Sources

For complete application attribution, consider:

Using user.registration.create events when users first register to applications Combining user.login.success events with application-level audit logs Implementing custom event enrichment in your webhook consumer that correlates login events with subsequent token validation Important Note

Self-service registration, if enabled, allows anyone to register to that application. Your applications should always validate that the user has a proper registration (jwt.applicationId) and any other business-specific claims required for access.

Both entry points, and especially the anti-enumeration behavior on the known-tenant path, are best built by calling FusionAuth's passwordless APIs directly from your own UI rather than relying on the hosted login pages. Here's more on the difference.

Using the API is the only way to get full control over what the UI shows on a failure.

Known-tenant entry (acme.ourapp.com) Maintain your own slug/domain → tenantId table (outside FusionAuth), populated when you provision each tenant via the Tenant API. FusionAuth has no built-in hostname-to-tenant mapping. You can learn more in the multi-tenant guide. At request time, resolve the subdomain to a tenantId from that table (outside FusionAuth). If nothing matches, show "Workspace not found" — this never touches FusionAuth. Build your own "enter your email" screen for this workspace (not FusionAuth's hosted page — you need to control what's shown on failure, which the hosted page won't let you do). When the user submits an email, your backend calls /api/passwordless/start with that tenantId + your Universal Application id + the email as loginId. Universal Application docs here. Branch on the response, entirely inside your backend: 200, code sent → hang onto the returned code value, respond to your frontend with a generic "we sent you a code" message, and show your own "enter the code" screen. 404, no user found → this is the real signal Slack is hiding. FusionAuth returns a 404 with an empty body when no user matches the tenant. Instead of surfacing that: send your own "no account with this email in this workspace" notice through your own transactional email provider (outside FusionAuth or using the send email API), then respond to your frontend with the exact same "we sent you a code" message. Show the identical "enter the code" screen either way. Completing the challenge: Real branch: verify the code the user types via /api/passwordless/login (tenantId + code), which returns tokens; pair this with the Hosted Backend / BFF if it's a SPA. Alternatively, redirect the browser to /oauth2/passwordless/{code}?tenantId=<tenantId>&client_id=<id> and let FusionAuth's hosted page take over the code-entry step. This is the URL FusionAuth's own passwordless email template constructs for the "click to log in" link, so redirecting there yourself just skips the email round-trip. Fake branch: there is no FusionAuth code to hand off, so there's nothing to redirect to on FusionAuth's hosted domain — you have to own the "enter code" screen yourself here. Whatever the user types, respond with the same generic "invalid or expired code" error you'd give a real wrong code; never a distinct message. If you're using the hosted-page redirect for the real branch, don't try to fake that redirect for this branch — just render your own equivalent screen and always reject, rather than attempting a look-alike hosted destination. Pad the fake branch's response time to roughly match a real Start call, so the two paths don't diverge on timing, which would leak the same thing you're hiding in the UI. Generic entry (ourapp.com/login) Call /api/user/search with a global (not tenant-scoped) API key and no tenantId filter, searching by the submitted email. Each matching User record already includes its own tenantId, so this single call tells you every workspace the email belongs to. This pattern (global key, /api/user/search?queryString=<email>, results include per-tenant matches) is answered on the forum. Keep the key server-side only. If you'd rather not run a global-key search on every anonymous request (latency, or wanting the key confined to a webhook receiver instead of a public endpoint), you can maintain your own email → tenantId[] table fed by FusionAuth's user.create / user.update / user.delete webhooks instead. Docs at https://fusionauth.io/docs/extend/events-and-webhooks/. Either is fine — this is a trade-off, not a hard requirement. Branch on the result (outside FusionAuth): No match → "No account found," stop there. One match → continue with that tenant. Multiple matches → show a workspace picker, then continue with the chosen one. This is currently functionality you have to build yourself, though there is an open issue. Once a tenant is resolved, it's the same steps as section 1 from "build your own enter-email screen" onward — including the fake-challenge branch, if you want the same anti-enumeration behavior here too (Slack's generic "find your workspaces" entry also avoids confirming or denying a match directly, for the same reason). A few things worth flagging FusionAuth users are tenant-scoped records — the same person needs a separate User object per workspace they belong to. API key scope matters: the cross-tenant search in section 2 needs a global key; the tenant-specific calls in section 1 can safely use a tenant-scoped key. [Docs](Docs at https://fusionauth.io/docs/apis/api-keys). The SSO session cookie isn't tenant-aware across hostnames — FusionAuth doesn't currently support true multi-tenant SSO through the hosted pages, so the user behavior when switching tenants requires another login. Always pass tenantId explicitly on every call. Passwordless API reference for the exact Start/Login request and response shapes:

This behavior is likely due to changes introduced in FusionAuth 1.68.0 related to Intelligent MFA and Risk Signals.

Starting in 1.68.0, FusionAuth uses a variety of "Risk Signals" to determine when to trigger the Suspicious Login email. The email is sent whenever any enabled risk signal returns a HIGH value. One common signal that can cause this is:

DormantPassword: This signal triggers when a user's password hasn't been changed "in the last few months." If your users do not regularly rotate their passwords, this risk signal could be flagging every login as suspicious. Solution

You can fine-tune which Risk Signals are considered for your tenant:

Navigate to Tenants > Edit Tenant > Security > Customize Risk Signals Review the enabled risk signals Consider toggling off the Dormant Password signal if password rotation is not part of your security model, or adjust other signals as appropriate for your use case Testing

To verify this is the cause:

Try changing a user's password, then logging in again to see if the suspicious login email still triggers Alternatively, disable the Dormant Password risk signal temporarily and test login behavior

This should allow you to re-enable suspicious login notifications while avoiding false positives for normal login activity.

No, you cannot configure the same custom domain on two different FusionAuth Cloud deployments at the same time.

The recommended migration sequence is:

Remove the custom domain from the production deployment Configure the custom domain on the dev deployment Configure a CNAME record pointing your custom domain directly to the dev deployment's durable hostname Validate the certificate for the domain on the dev deployment Important Considerations

DNS Propagation Time

DNS changes take time to propagate Expect up to 30 minutes for DNS servers to recognize the changes Propagation may take longer depending on your DNS TTL settings Plan for this downtime window during your migration

Certificate Validation

Certificate validation uses DNS-based methods You must complete the DNS configuration before certificate validation can succeed

To minimize downtime, prepare all configurations on the dev deployment beforehand, then execute the domain removal, DNS update, and certificate validation in quick succession.

FusionAuth does not perform Unicode normalization on passwords before hashing.

Passwords are hashed using the raw bytes exactly as received from the client. This means:

If a user sets a password with Unicode characters, those exact byte sequences are hashed Different Unicode representations of visually identical characters (e.g., é as a single composed character U+00E9 vs. e + combining acute accent U+0065 U+0301) will result in different password hashes No normalization forms (NFC, NFD, NFKC, NFKD) are applied

This behavior means you should ensure consistent encoding at the application level if Unicode normalization is important for your use case. The password validation will only succeed if the exact same byte sequence is provided during authentication.

Additional Context

FusionAuth fully supports Unicode characters in passwords, which is recommended for both usability and security reasons. When FusionAuth validates passwords for special characters, it processes them as Unicode strings (using Java's Character.isAlphabetic() and Character.isDigit() methods on 16-bit Unicode values), confirming that passwords are handled as Unicode throughout the system.

There are no inherent limitations on which Unicode characters can be used in passwords stored in FusionAuth, though you can configure password validation rules to enforce specific requirements for your tenant.

Related Documentation Password-Hashing Algorithms - Overview of FusionAuth's password hashing schemes (PBKDF2, Bcrypt, etc.) Custom Password Hashing - Information on implementing custom password hashing schemes Password Validation Rules - API for retrieving and configuring password validation rules Client-side Password Rule Validation - Guide for implementing password validation in your client application Are there any disallowed characters in passwords? - Community discussion confirming no inherent character limitations

There are several ways to monitor your hosted FusionAuth deployment:

Basic Health Monitoring

You can use the System Status API to get basic information about your deployment, including whether it is healthy. For dedicated health checks (particularly useful for load balancers), there's also the Health API available since version 1.51.1.

Detailed Metrics with Prometheus

For more detailed performance monitoring, you can configure Prometheus to retrieve system metrics from FusionAuth. FusionAuth exposes:

JVM-level gauges: memory usage, garbage collection stats, thread counts, class loading, buffer pools Request timers: endpoint latency and request counts (e.g., prime_mvc_* metrics)

You can then set up Prometheus dashboards to visualize this data and track CPU, memory, and other performance metrics over time.

See the FusionAuth Prometheus documentation for configuration details and the Prometheus Metrics API for endpoint information.

Important Considerations for Hosted Deployments

If your hosted FusionAuth deployment has multiple compute nodes, be aware that both the Status API and Prometheus metrics endpoints return data per-node. Since requests are round-robined across nodes, successive API calls may hit different nodes and return inconsistent data. This makes direct polling less reliable for multi-node deployments.

Additional Monitoring Options

Beyond Prometheus, FusionAuth can integrate with other monitoring tools:

Datadog: Use the Datadog Agent with OpenMetrics integration CloudWatch: Monitor FusionAuth metrics in AWS environments Grafana: Visualize Prometheus data with pre-built dashboards

You can also access:

System logs: Available via API (exportable as ZIP files) Audit logs: Track administrative actions via API or webhook Event logs: Debug information for external integrations Login records: Successful login history with timestamps, IPs, and user details Webhooks: Get real-time notifications for specific events Related Documentation Monitoring FusionAuth Overview System Status API System Health API Prometheus Integration Guide Prometheus Metrics API Datadog Integration CloudWatch Integration

Yes, successfully logging in with a passkey will update the user's last login instant.

However, there are edge cases where a passkey can be used without updating the last login timestamp:

Scenarios where passkey use doesn't update last login:

Login flow interrupted — The user authenticates with the passkey, but the login is stopped before completion due to:

Failed MFA challenge User action requirement (e.g., forced password reset) Account lock or suspension Login validation Lambda or transactional webhook rejecting the login

WebAuthn assertion without login — If the user performed a WebAuthn assertion directly via the API, this counts as using the passkey but does not constitute a full login flow and therefore doesn't update the last login instant. The Complete a WebAuthn Passkey Assertion API validates the WebAuthn ceremony but "does not authenticate the user into an application." This is different from the Complete a WebAuthn Passkey Authentication API, which validates the passkey and authenticates the user, thus updating the last login instant.

Summary

A passkey being "used" is not the same as a completed login. The last login timestamp only updates when the authentication flow completes successfully and issues a token.

Related Documentation Complete a WebAuthn Passkey Authentication - The API that validates passkeys and authenticates users (updates last login) Complete a WebAuthn Passkey Assertion - The API that only validates passkeys without authenticating (does not update last login) Authentication With WebAuthn & Passkeys - Complete guide to WebAuthn/passkey authentication in FusionAuth Update Login Instant API - Manual API for updating login instants when implementing custom SSO Setting Up User Account Lockout - How account lockouts can interrupt login flows

You can use the User Search API with a must_not clause in the Elasticsearch query to exclude users registered to a specific application. Here's an example:

curl -X POST https://sandbox.fusionauth.io/api/user/search \ -H 'Authorization: <your-api-key>' \ -H 'Content-Type: application/json' \ -d '{ "search": { "accurateTotal": true, "numberOfResults": 100, "startRow": 0, "query": "{\"bool\":{\"must_not\":[{\"nested\":{\"path\":\"registrations\",\"query\":{\"bool\":{\"must\":[{\"match\":{\"registrations.applicationId\":\"<your-application-id>\"}}]}}}}]}}" } }'

Key points:

The must_not clause excludes users matching the nested query The nested query targets the registrations path since registrations are nested objects in the Elasticsearch mapping Inside the nested query, the must clause matches the specific applicationId Replace <your-application-id> with the UUID of your target application This returns users who either have no registrations at all, or have registrations to other applications but not the specified one

You can paginate through results using startRow and numberOfResults if you have a large user base.

Important: This approach requires the Elasticsearch search engine (not the database engine). You must use the search.query parameter with raw Elasticsearch JSON when querying against registrations, because it is defined as a nested datatype in the Elasticsearch mapping. The queryString parameter cannot be used for nested fields like registrations with expected results.

Tip: You can use the Admin UI → Users → Advanced → Show Elasticsearch Query toggle to build and test queries interactively before using them in the API.

Related Documentation User Search API - Elasticsearch Search Engine - Main API reference for searching users with Elasticsearch Searching Users With Elasticsearch or OpenSearch - Searching With query - Guide on using the query parameter for advanced searches User Search API - Additional Query Examples - Examples of various query patterns including nested queries Registrations - Core concepts documentation explaining the relationship between Users, Applications, and Registrations Field Mappings - Available fields for matching in Elasticsearch searches

You do not need to reindex users after upgrading FusionAuth.

The reindexing process will not impact:

Users' ability to log in User registration for applications

However, there may be a small increase in load times if the reindex occurs during a high-traffic period for your application. The reindexing primarily affects search and user count operations in the administrative console, not end-user authentication flows.

If you do choose to reindex (for other reasons such as search optimization), it can be done safely without blocking user authentication.

Additional Context

When Would Reindexing Be Needed?

While upgrading FusionAuth typically does not require reindexing, there are specific scenarios where it may be necessary:

Specific version upgrades: Certain version upgrades may require a reindex—this is always noted in the release notes. For example, version 1.17.2 noted: "A reindex may be necessary depending on how you have upgraded your Elasticsearch cluster." Database restoration: If you restore FusionAuth from a database dump without migrating the search index, you will need to reindex. User imports: If you import users via the User Import API, a reindex may be needed. Search engine switching: When switching from the database search engine to Elasticsearch, a reindex is required.

In general, even after a temporary Elasticsearch outage, the index will sync up automatically without manual reindexing.

Why Authentication Is Unaffected

Elasticsearch is only used for search operations in the admin UI and search APIs—it is not queried during authentication. FusionAuth does attempt to update the Elasticsearch index during authentication, but this is done asynchronously (since version 1.30.2) and is not required to complete the login. This means that even if Elasticsearch is temporarily unavailable or reindexing, authentication should not be blocked.

Performance Considerations

Reindexing is an expensive operation and should be avoided unless necessary. It causes additional CPU and I/O overhead until complete. However, performance has been significantly improved in recent versions, and beginning in version 1.48.0, index aliases are used to minimize disruption to API requests during a reindex.

Related Documentation Upgrade FusionAuth Guide - Best practices for upgrading FusionAuth Release Notes - Always check for version-specific reindexing requirements Re-indexing Documentation - When and why reindexing might be needed Rebuild the Elasticsearch Index API - How to trigger a reindex programmatically Switching Search Engines - Guide for switching between database and Elasticsearch search