WebAuthn Client Hints

WebAuthn client hints

Client hints are optional values sent by the relying party (RP) to help the browser prioritize authenticators during passkey flows, optimizing the user experience.

Why use client hints?

Client hints help optimize the user experience by guiding the browser to prioritize the preferred authenticator. Authentication flows often present users with multiple options at once, which can lead to decision fatigue or accidental selection of a less secure option.

Common problems users face include:

Enterprise users with security keys being prompted to use their phone instead
Inconsistent behavior across browsers, platforms and devices
Lack of guidance when both platform and roaming authenticators are available

Here are some examples of where client hints can help:

Prioritizing a security key (such as a YubiKey) when high assurance is required, such as in apps that handle personally identifiable information, financial data or sensitive communications like banking, healthcare, journalism or political campaigns
Prioritizing platform authenticators like Face ID or Windows Hello in low-assurance consumer apps where convenience is the focus
Avoiding QR codes when only security keys are expected

Note	Client hints do not reveal which authenticators are present on the device, helping preserve user privacy and security.

Supported hint values

Client hints are passed in an ordered array in the hints field. They can be included in either registration or authentication requests.

Supported values include:

Hint	Description
`"security-key"`	Suggests using a roaming authenticator like a YubiKey.
`"client-device"`	Suggests using a platform authenticator like Windows Hello.
`"hybrid"`	Suggests a cross-device flow, such as using a smartphone for passkey login.

Warning

Browsers that do not support the hints field will silently ignore it and proceed with default behavior. Passing an empty hints array or omitting the property entirely indicates no preference and shows standard WebAuthn options.

Using multiple hints

You can pass multiple hints in the array to offer fallback options. Browsers prioritize the first hint and may fall back to others if unavailable.

Example

"hints": ["security-key", "client-device"]

In this example, the browser will try to show a security key first. If unavailable, it may fall back to a platform authenticator.

Video demo: client hints in action

Watch this short demo to see how different hints values impact the WebAuthn prompt.

How client hints differ from `authenticatorAttachment`

authenticatorAttachment is an authoritative directive that tells the browser which types of authenticators are allowed. In contrast, client hints are optional suggestions that help the browser improve the user experience by ordering options in a more intuitive way.

Use both together for the best experience: authenticatorAttachment enforces requirements, while client hints guide user interface behavior by suggesting a preferred authenticator order.

Feature	`authenticatorAttachment`	`client hints` (`hints`)
Purpose	Filters allowed authenticator types	Suggests preferred authenticator types
Enforced by browser?	✅ Yes: operation fails if no match	❌ No: advisory only, ignored if unsupported
Fallback behavior	Blocks if no matching authenticator is available	Silently proceeds with default behavior
Browser support	Widely supported across all major browsers	Varies by browser and platform. Check platform support

To ensure compatibility with older browsers that don’t support hints, always set authenticatorAttachment to align with your hint type. For example:

"security-key" → cross-platform
"client-device" → platform
"hybrid" → cross-platform

Browsers that don’t recognize hints will still honor authenticatorAttachment, preserving expected behavior.

For more details on how to use authenticatorAttachment, see the Passkey Workshop registration flow documentation.

Implementation guidance

To implement client hints, add the hints property to PublicKeyCredentialCreationOptions for create() calls, and PublicKeyCredentialRequestOptions for get() calls. Examples of both are shown below.

Example: registration options with hints

"publicKey": {
  "rp": ...,
  "user": ...,
  "challenge": "uhUjPNlZfvn7onwuhNdsLPkkE5Fv-lUN",
  "pubKeyCredParams": ...,
  "authenticatorSelection": ...,
  "attestation": "direct",
  "hints": ["security-key", "client-device", "hybrid"]
}

Example: authentication options with hints

"publicKey": {
  "challenge": "NGc3jpB4Q-VnOmbhFBnDAczlYPT4soKA7xviGeJmDhc",
  "timeout": 180000,
  "rpId": "localhost",
  "userVerification": "preferred",
  "hints": ["security-key", "client-device", "hybrid"]
}

The Yubico webauthn-server-core library defines the PublicKeyCredentialHint class, which defines the supported hint values. For full reference, see the API documentation: PublicKeyCredentialHint JavaDoc

Platform support

Before implementing client hints, verify that your target browser, operating system or device supports client hints.

For details on browser and platform compatibility, visit the WebAuthn Browser Support – Client Hints

Additional resources

For more information, see the W3C explainer on client hints: Explainer: Hints for WebAuthn Clients