> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corbado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Passkey Login: Conditional UI

> Usernameless login flow in which the browser links eligible passkey suggestions to the identifier field.

## Conditional UI Flow (Usernameless Login)

Conditional UI lets the user select a passkey from the username or email field without entering the identifier first. That one selection completes both parts of login: the credential ID tells the server which account and user pool to use, and the verified assertion authenticates the user.

> [!NOTE]
>
> **Implementation prerequisite:** Conditional UI is not automatic: your page must call `navigator.credentials.get({ mediation: 'conditional' })` and mark the input with `autocomplete="username webauthn"`. Without both, nothing is offered. It is available in all modern web browsers. Use `isConditionalMediationAvailable()` because browser support does not guarantee that every operating system and credential-provider combination can offer a passkey.

Eligible passkeys can appear in different system autofill surfaces depending on the platform, including a keyboard suggestion, sheet, overlay or desktop dropdown. The browser and active credential providers control which credentials are shown.

> [tab] macOS
>
> ![macOS Conditional UI flow](https://docs.corbado.com/images/authentication-flow/web-app/desktop/autosuggest-passkeys-macos.webp)
>
> macOS Conditional UI flow
>
> Download macOS Conditional UI flow (Download image)

> [tab] Windows
>
> ![Windows Conditional UI flow](https://docs.corbado.com/images/authentication-flow/web-app/desktop/autosuggest-passkeys-windows.webp)
>
> Windows Conditional UI flow
>
> Download Windows Conditional UI flow (Download image)

> [tab] iOS
>
> ![iOS Conditional UI flow](https://docs.corbado.com/images/authentication-flow/web-app/mobile/autosuggest-passkeys-ios.webp)
>
> iOS Conditional UI flow
>
> Download iOS Conditional UI flow (Download image)

> [tab] Android
>
> ![Android Conditional UI flow](https://docs.corbado.com/images/authentication-flow/web-app/mobile/autosuggest-passkeys-android.webp)
>
> Android Conditional UI flow
>
> Download Android Conditional UI flow (Download image)

**1. Make Conditional UI available**

* The page starts the conditional request before the field can be used and focuses the annotated username or email field where the platform supports it.
* When the field is focused, the browser or operating system can show eligible discoverable passkeys from the active credential providers.
* The presentation varies by platform: keyboard suggestion, system sheet or overlay on mobile, or a desktop dropdown. Conditional mediation remains non-blocking to the page.
* At this point, the relying party does not know which account is signing in.

**2. Select and authorize a passkey**

* The user selects a passkey from the available options.
* User verifies their identity using their screen lock (e.g., fingerprint, PIN, or face recognition).
* The browser returns the credential ID and signed assertion to the application.

**3. Resolve the account and validate login**

* The server uses the credential ID to find the account and correct user pool, then verifies the assertion.
* It applies the same account-status and login-policy checks used by every other login route.
* A wrong user pool, stale credential or blocked account receives its specific message and next action instead of a session.

**4. Complete login**

* Only a valid assertion for an account that may sign in creates a session.
* If One-Tap is enabled, this successful passkey login makes One-Tap eligible for the account in the current browser profile.

> [!WARNING]
>
> **The server still decides whether login succeeds.** If it no longer accepts the selected passkey, show a clear stale-passkey message with retry and fallback. When the credential ID is conclusively unknown, a supporting browser can receive `signalUnknownCredential`. This is best effort and does not prove that the provider removed the passkey. See the [WebAuthn Signal API](https://docs.corbado.com/passkey-ui-flows/web/signal-api.md).

## Acceptance criteria

| Benchmark as | User reach |
| - | - |
| Enhancement | High |

Conditional UI combines account discovery and authentication. The selected discoverable credential identifies the account, and its assertion proves the login. The user does not submit an identifier first. Conditional UI still needs a normal login and fallback route beside it.

`W1.2-AC05` applies when the page supports multiple user pools or sign-in areas. `W1.2-AC08` applies where the WebAuthn Signal API is supported. `W1.2-AC09` applies when One-Tap is enabled.

| ID | Level | Acceptance criterion | How to verify |
| - | - | - | - |
| **W1.2-AC01** | Core | Start Conditional UI only when WebAuthn and conditional mediation are available. Test every claimed browser, operating-system and credential-provider combination with a real passkey instead of relying only on browser versions. | Test a missing WebAuthn API, a missing capability method, a rejected capability check and a `false` result. None starts Conditional UI. Then complete the flow on every combination listed as supported. |
| **W1.2-AC02** | Core | Before the sign-in field can be used, start one discoverable `navigator.credentials.get()` request with `mediation: "conditional"` and an empty or omitted `allowCredentials`. Mark the field with an autocomplete value ending in `webauthn`, normally `username webauthn`. An eligible passkey can appear at the latest on the first user focus; focusing the field when the view opens is a recommended enhancement, not a requirement of this criterion. | Inspect the request and rendered field before interaction. On every supported target, open the login view with an eligible passkey and confirm that the first supported focus can show it. |
| **W1.2-AC03** | Core | Conditional UI does not block or change identifier-first login, password login or fallback. No eligible passkey, an ignored suggestion and dismissal remain silent. Abort the conditional request before starting an account-scoped or modal passkey request, and ignore any late result from the old request. | Test no eligible credential, an ignored suggestion and dismissal, then submit an identifier, start automatic identifier-first passkey login, choose fallback and navigate away. The normal form remains unchanged, no application error or overlapping prompt appears and no late Conditional UI result creates a session. |
| **W1.2-AC04** | Core | Keep only one Conditional UI request active on the page. Multiple login forms, flyouts or user pools share one coordinator. When the active surface or user pool changes, abort the old request and start a fresh request with the challenge and `AbortController` for the new context. | Render a general login form and a flyout for the same and different user pools. Switch between them and confirm that only the active context has a request and that every restart uses fresh server options and a new controller. |
| **W1.2-AC05** | Core | When the server knows that the selected passkey belongs to a different user pool or sign-in area, do not authenticate it in the current pool. Show a specific message and take the user to the matching sign-in route or an available fallback. | Select a credential from another supported user pool. Confirm that no session is created in the current pool, the message explains the mismatch and its next action opens the correct route. |
| **W1.2-AC06** | Core | After the selected passkey identifies an account, verify the assertion and apply the same account-status and login-policy checks as every other route before creating a session. Closed, deleted, disabled, inactive, locked or restricted accounts cannot bypass those checks through Conditional UI. | Test each account state with a valid passkey. Only an account allowed to sign in creates a session; every blocked state shows its configured message or recovery route. |
| **W1.2-AC07** | Core | When the server rejects the selected credential as stale or no longer accepted, show a clear message that the passkey can no longer sign in and offer "Try another passkey" plus the available fallback. Cancellation remains silent. | Submit a credential deleted through account settings and another credential the server no longer accepts. Confirm the message and both next actions. Then cancel the selection and confirm that no error appears. |
| **W1.2-AC08** | Quality | When the credential ID is conclusively unknown to the server, call `signalUnknownCredential` on supporting browsers. Do not send this signal for a known revoked credential, invalid signature, network failure or cancellation. The signal is best effort and does not block login or prove that the provider removed the passkey. | Submit each result and inspect Signal API calls. Only the confirmed unknown credential emits the correct RP ID and credential ID; rejection or absence of the API does not block retry or fallback. |
| **W1.2-AC09** | Quality | When One-Tap is enabled, a successful Conditional UI login makes One-Tap eligible for that account in the current browser profile. A cancelled, failed, stale or wrong-pool attempt does not. | Complete each result and reload the login page. Only the successful server-verified Conditional UI login enables One-Tap for the authenticated account. |

### References

* **Relevant criteria:** `W1.2-AC01`–`W1.2-AC08`. [Web Authentication: An API for accessing Public Key Credentials: Level 3](https://www.w3.org/TR/webauthn-3/) defines conditional capability detection, discoverable credentials, the `webauthn` autocomplete token, request cancellation, server-side assertion verification and `signalUnknownCredential`.
* **Relevant criteria:** `W1.2-AC02`–`W1.2-AC04`. [Credential Management Level 1](https://www.w3.org/TR/credential-management-1/) defines conditional mediation as non-modal and user-mediated and explains why an ignored or unavailable suggestion does not resolve the request.
* **Relevant criteria:** `W1.2-AC01`–`W1.2-AC04`, `W1.2-AC07`. [Passwordless sign-in on forms with WebAuthn passkey autofill](https://developer.chrome.com/docs/identity/webauthn-conditional-ui) documents capability-aware form integration, focus behavior and coexistence with the conventional login form.
* **Relevant criteria:** `W1.2-AC03`–`W1.2-AC09`. [WebAuthn Conditional UI technical explanation](https://www.corbado.com/blog/webauthn-conditional-ui-passkeys-autofill) provides implementation experience for request coordination, account resolution, cancellation, stale credentials and later login behavior; it is practical guidance rather than the normative source.
* **Relevant criteria:** `W1.2-AC08`. [Chrome for Developers: Keep passkeys consistent with credentials on your server](https://developer.chrome.com/docs/identity/webauthn-signal-api) documents the confirmed unknown-credential trigger and best-effort signal behavior.
* **Relevant criteria:** `W1.2-AC09`. [One-Tap Login: Seamless Passkey Authentication](https://docs.corbado.com/corbado-connect/features/one-tap-login.md) documents the returning-user state that makes One-Tap available after successful passkey use.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.