WebAuthn Immediate Mediation explained

60-page Enterprise Passkey Whitepaper:
Learn how leaders get +80% passkey adoption. Trusted by Rakuten, Klarna & Oracle

Get free Whitepaper

The transition to passkeys is creating a "passkey paradox": some users have passkeys, while many still use traditional passwords. This leads to cluttered login screens with multiple buttons: "Sign in with Password", "Sign in with Google" and "Sign in with Passkey". This fragmentation causes friction. A user might click "Sign in with Passkey" on a new device only to face a confusing QR code prompt because their passkey isn't locally available. The core problem is the website's inability to know the user's context before initiating an authentication flow.

One solution is going identifier-first and determining the best login method for the user. Another potential solution is a single, intelligent "Sign In" button that orchestrates the most seamless flow for each user. It should directly prompt for a passkey if one is available on the device, or gracefully fall back to other methods if not.

There is a new WebAuthn feature announced that could make this possible: Immediate Mediation (mediation: 'immediate'). By setting this property in a WebAuthn API call, developers can build an intelligent, unified sign-in experience that solves the passkey paradox. This article provides a developer-focused analysis into mediation: 'immediate', exploring what it is, how it works, and how to implement it.

To understand Immediate Mediation, it's helpful to first know the other options. User mediation in WebAuthn is how the browser manages the interaction between your website (the Relying Party) and the user's authenticator (e.g., Face ID, YubiKey).

This is the classic, explicit WebAuthn flow. When a Relying Party calls navigator.credentials.get() without specifying a mediation preference, the browser always presents a modal dialog. This dialog overlays the page content, demanding the user's immediate attention and pausing all other interaction with the website.

• Use Case: Best for dedicated "Sign in with Passkey" buttons where the user has clearly stated their intent.
• Limitation: If the user doesn't have a passkey on the current device, they are shown a cross-device flow (e.g., QR code), which can be a confusing dead end.

Want to experiment with passkey flows? Try our Passkeys Debugger.

Try for Free

Introduced to help users transition to passkeys, this mode is more subtle. With mediation: 'conditional', the WebAuthn request is attached to an input field (e.g., username) with the autocomplete="webauthn" attribute. When the user clicks the field, the browser's autofill UI suggests any available passkeys.

• Use Case: Ideal for progressively enhancing traditional login forms, allowing users to discover and use passkeys without a separate button.
• Limitation: It prioritizes privacy so strictly that if the user has no passkey or doesn't interact with the prompt, the API call's promise never resolves. The website gets no signal, making it impossible to orchestrate a fallback UI.

mediation: 'immediate' is the solution for the "single sign-in button" problem. It provides a reliable way for a website to check for a passkey's availability before showing any UI.

Instead of telling the user to authenticate with a passkey via a modal, immediate mediation asks the browser: "Is there a passkey readily available for this user on this device right now?"

Crucially, this query only checks for locally-available credentials (e.g., on-device authenticators like Windows Hello or passkeys synced via a password manager). It is designed to avoid triggering the cross-device QR code flow, which is a common friction point.

Want to try passkeys yourself in a passkeys demo?

Try Passkeys

The power of this feature lies in its clear, binary outcome. The promise returned by navigator.credentials.get() will either succeed or fail, giving the developer a clear signal.

• Path 1 (Success): A Credential Exists. If the browser finds a locally available passkey, it bypasses the website's UI and immediately presents its own native modal, such as an account chooser. If the user successfully authenticates, the promise resolves with the PublicKeyCredential object.
• Path 2 (Failure): No Credential Exists. If the browser finds no locally available credentials, it shows no UI. Instead, the navigator.credentials.get() promise immediately rejects with a DOMException named NotAllowedError.

The NotAllowedError is not a bug. It's more like a feature. It is a reliable, instantaneous signal that the website should proceed with a fallback authentication method. This allows developers to use a simple try...catch block: the try block attempts the seamless passkey flow, and the catch block listens for NotAllowedError to render a traditional login form. It elegantly solves the single sign-in button problem by creating one entry point that intelligently adapts to the user's context.

Choosing the right mediation mode is a critical UX decision. This table provides a side-by-side comparison.

Here is a practical, step-by-step guide to implementing mediation: 'immediate'.

Since mediation: 'immediate' is a new feature, robust feature detection is crucial.

// Feature detection is essential for progressive enhancement.
let immediateMediationAvailable = false;
 
if (window.PublicKeyCredential && PublicKeyCredential.getClientCapabilities) {
    try {
        const capabilities = await PublicKeyCredential.getClientCapabilities();
        // The 'immediateGet' capability signals browser support.
        immediateMediationAvailable = capabilities.immediateGet === true;
    } catch (e) {
        console.error("Error getting client capabilities:", e);
    }
}

This call must be triggered by a user gesture, like a button click.

// This function should be the event handler for your primary "Sign In" button.
async function handleSignInClick() {
    if (!immediateMediationAvailable) {
        // Fall back to showing a legacy login form if the feature isn't supported.
        showLegacyLoginForm();
        return;
    }
 
    try {
        // Fetch a fresh, random challenge from your server for each attempt.
        const challenge = await fetchChallengeFromServer();
 
        const publicKeyCredentialRequestOptions = {
            challenge: challenge, // The server-provided challenge as a Uint8Array
            rpId: "example.com",
            // The allowCredentials list MUST be empty for immediate mediation
            // to protect user privacy.
            allowCredentials: [],
        };
 
        const credential = await navigator.credentials.get({
            publicKey: publicKeyCredentialRequestOptions,
            // This is the key that enables the immediate mediation flow.
            mediation: "immediate",
        });
 
        // If the promise resolves, send the credential to your server for verification.
        await verifyCredentialOnServer(credential);
    } catch (error) {
        // The catch block is a critical part of the control flow.
        handleAuthError(error);
    }
}

The catch block is where the "intelligence" of the single sign-in button is realized.

// Handling the NotAllowedError is the key to the fallback mechanism.
function handleAuthError(error) {
    // Check the 'name' property of the DOMException.
    if (error.name === "NotAllowedError") {
        // This is the expected signal to show the traditional login form.
        console.log("No local passkey found. Showing legacy login form.");
        showLegacyLoginForm();
    } else {
        // This handles other potential errors, like the user dismissing the prompt.
        console.error("Authentication error:", error);
    }
}

For the most seamless experience, you can ask the browser to search for both passkeys and saved passwords in the same request by adding password: true.

// Combining passkeys and passwords for a truly unified sign-in experience.
const credential = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    password: true, // Ask the browser to include saved passwords.
    mediation: "immediate",
});
 
// The returned 'credential' object will either be a PublicKeyCredential
// or a PasswordCredential. Your server-side logic must handle both.

1. Concurrent WebAuthn Requests: A pending conditional request (often started on page load) can block a new immediate request. Consider using an AbortController to cancel any pending requests before starting a new one.
2. The allowCredentials Restriction: The allowCredentials array must be empty. Providing credential IDs will cause the call to fail. This is a crucial privacy safeguard to prevent sites from checking for specific, known users.
3. The User Gesture Requirement: The call must be initiated from a user gesture (e.g., a 'click' event). Calling it programmatically on page load will be blocked by browsers as a privacy protection measure.

mediation: 'immediate' was designed with a clear understanding of its security and privacy trade-offs.

The core trade-off is a "one-bit leak." By timing the promise's resolution, a Relying Party can infer one bit of information: whether the promise rejected instantly (no local credential) or was delayed (a UI prompt was shown because a local credential was found). The purpose of this leak is to enable a better UX.

The designers anticipated the potential for abuse (e.g., user tracking) and built-in several non-negotiable safeguards:

1. Mandatory User Gesture: The API call must be triggered by a user action like a click. This prevents a site from silently probing for accounts on page load and makes large-scale fingerprinting impractical.
2. Disabled in Private/Incognito Mode: The feature is disallowed in private browsing modes to prevent linking a user's activity between normal and private sessions.
3. Forbidden allowCredentials List: The allowCredentials array must be empty. This prevents a site from using this feature to check if a specific known user is visiting.
4. First-Party Context Only: The feature is disallowed in third-party contexts (e.g., an iframe from another origin) to prevent cross-site tracking.

These mitigations ensure that the core security guarantees of WebAuthn remain untouched. The authentication ceremony itself is unchanged and remains phishing-resistant.

mediation: 'immediate' is an advanced feature from the WebAuthn Level 3 specification, and its rollout is ongoing. As of mid-2025, a progressive enhancement strategy is essential.

While mediation: 'immediate' provides a great, low-level tool for a smarter login button, it's important to distinguish it from a broader "Passkey Intelligence" solution, such as the one offered by Corbado. Both aim to solve the passkey paradox and increase adoption, but they do so in different ways.

Passkey Intelligence goes a step further by collecting and evaluating data over time. This allows for more sophisticated and timely user interventions. For example, a Passkey Intelligence backend can detect:

• A user successfully authenticating with a password on a new, passkey-capable device and prompt them to add a passkey for next time.
• A user completing a cross-device "hybrid" login and immediately suggesting they register the new device.
• A user failing to log in on a new device and offering passkey creation as a recovery or setup option (automatic healing).

This data-driven approach is independent of browser support for mediation: 'immediate', meaning it can provide a more intelligent login flow for all your users, right now.

The Best of Both Worlds

Ultimately, these two approaches are not mutually exclusive; they are complementary. The ideal solution combines them:

1. Use a Passkey Intelligence service as the brain of your login process.
2. The service can then use mediation: 'immediate' as one of its signals on supported browsers to perform a quick, initial check.
3. Based on the result—or the lack of support for the feature—the intelligence service can then use its richer, historical data to orchestrate the perfect fallback, whether it's showing a password field or offering a just-in-time passkey creation prompt.

By combining the native speed of mediation: 'immediate' with the deep insights of a Passkey Intelligence backend, you can provide the most seamless, adaptive, and effective login experience possible, gently guiding every user towards a passwordless future.

Immediate Medation is great upgrade to the login experience. It provides the intelligence needed to eliminate common points of friction and confusion for users during the transition to passkeys.

• Reduces User Confusion: By enabling a single "Sign In" button, immediate mediation removes the cognitive load for the user. They no longer have to remember which authentication method they set up or choose from a cluttered list of options. The login process becomes simpler and more intuitive.
• Prevents Passkey Aborts: A common reason users abandon a passkey login is the unexpected appearance of a QR code for a cross-device flow. Because mediation: 'immediate' only looks for local credentials, it avoids this confusing state entirely. Instead of the user aborting the flow, the application receives a clear signal (NotAllowedError) to gracefully fall back to another method, resulting in a smoother journey.
• Creates a Seamless, Intelligent Flow: The core benefit is a smart login experience. The application can ask the browser if a seamless passkey login is possible before committing to a UI. This "Ask, Don't Tell" approach ensures users only see prompts that are relevant to them. It makes the login feel smart and adaptive, reinforcing the convenience of passkeys and encouraging their continued use.

Immediate Mediation is a new WebAuthn feature that solves the fragmented login experience of the passkey transition period. It enables the creation of a single, intelligent "Sign In" button that adapts to the user's context, eliminating confusion and friction. While it introduces a calculated privacy trade-off, it includes robust safeguards to mitigate risks without compromising the core security of WebAuthn.

For developers, the path forward is progressive enhancement. Build a solid baseline experience, and layer immediate mediation on top for supported browsers. Adopting this feature is a strategic move to accelerate passkey adoption, enhance security, lower operational costs, and improve conversion.

Implementing these advanced authentication flows can be complex. Corbado's Enterprise Passkey Platform abstracts away this complexity. Our infrastructure handles optimal flow orchestration—including conditional and immediate mediation allowing your team to deploy a state-of-the-art, frictionless authentication experience with confidence.