Passkey Login: Automatic Overlay

An OS-driven prompt requested before identifier entry or an OIDC system webview ceremony. This is a usernameless flow that can provide a fast login when an immediately available candidate is present. This flow uses immediate-only request behavior so the platform can return promptly instead of starting remote discovery when no immediate candidate is available. It does not guarantee success: the user can still cancel, a credential can be stale, or server verification can reject the assertion.

First Installation Delay: On first app installation, the automatic overlay may take some time to appear as the operating system needs to verify domain associations:

iOS: Verifies Associated Domains via the apple-app-site-association file
Android: Verifies Digital Asset Links via the .well-known/assetlinks.json file

These verification files determine which domains are authorized to use passkeys with your app. After association verification, later launches may avoid the first-install verification delay, but presentation timing and credential availability remain platform- and provider-dependent.

iOS
Android

Technical Implementation: This flow uses immediate-only request behavior so the platform can return promptly when no immediately available candidate is offered. On Apple platforms, use preferImmediatelyAvailableCredentials; on Android, configure Credential Manager to prefer immediately available credentials. On the web, feature-detect Chrome’s immediateGet capability and request uiMode: 'immediate'. These settings avoid remote discovery such as cross-device authentication, but they do not let the app enumerate local credential inventory or guarantee that a displayed candidate will authenticate successfully.

Product-Native Steps: The blue background indicates optional product-native steps (e.g., verification code, setup PIN, enabling biometrics). PIN and local biometrics are optional features for protecting app access within sessions after passkey authentication completes. Learn more about how passkeys and local biometrics work together to provide both secure remote authentication (passkeys) and convenient app protection (local biometrics).

OS presents the passkey overlay

The app requests the overlay when the login screen appears, before the user enters an identifier or an OIDC system webview ceremony starts.
This is a usernameless flow: the client or provider decides which eligible immediately available credentials to surface.
The app does not enumerate the provider’s local inventory or claim that every stored credential is shown.

User selects passkey and authenticates

User selects their passkey from the available options.
The system now knows which user account is authenticating.
User authorizes with a platform-supported device-unlock method, such as a biometric, PIN, pattern or device password.

App PIN setup

After successful passkey authentication, the user is signed in and is asked to set up PIN.

Enable local biometric for app login

User is allowed to enable/disable local biometric app login (provided as product feature).

Acceptance criteria

Benchmark as	User reach
Strategy	High

This strategy is applicable when the app can ask the operating system to limit the initial request to credentials that are immediately available. It can be layered with identifier-first or explicit login routes as the non-blocking fallback.

ID	Level	Acceptance criterion	How to verify
N1.1-AC01	Core	When an immediately available passkey exists, the signed-out entry screen invokes the operating-system credential selector before the user enters an identifier or an OIDC system webview ceremony starts.	On physical iOS and Android devices with a matching local passkey, cold-start the signed-out app and return to it from the background. Confirm that the selector is invoked before any identifier input or OIDC system webview ceremony.
N1.1-AC02	Core	When no immediately available credential exists, the local-only overlay request returns without starting remote or external credential discovery.	Test with no local passkey and with only a remote or external credential. Confirm that the request returns without a cross-device or security-key journey.
N1.1-AC03	Core	A result from a passkey ceremony started on an obsolete login screen cannot affect the current screen or session.	Navigate away while the selector is open, then complete or dismiss it. Confirm that the late result is ignored by the current screen and cannot create a session there.
N1.1-AC04	Quality	After the automatic ceremony closes, it is triggered again only after the user closes and reopens the login screen or closes and reopens the app, depending on the app architecture. Prompts do not stack, and the app does not create repeated login screens to retrigger the ceremony.	Dismiss the selector, then background and resume the app, repeat lifecycle events and rotate where supported. Confirm that the ceremony does not restart. Close and reopen the login screen or app through the architecture’s intended route and confirm that one new ceremony starts without adding repeated screens to the navigation stack.

References

Relevant criteria: N1.1-AC01–AC02: Apple: Prefer immediately available credentials and Android: GetCredentialRequest define the immediate-credential preference and remote-discovery boundary.
Relevant criteria: N1.1-AC03–AC04: Corbado: Testing Passkey Flows in Native Apps covers lifecycle, cancellation and physical-device acceptance testing.

Overview

Web

Native

Passkey Login: Automatic Overlay

Acceptance criteria

References

​Automatic Passkey Overlay (Usernameless Login)

​Acceptance criteria

​References

Automatic Passkey Overlay (Usernameless Login)

Acceptance criteria

References