---
url: 'https://www.corbado.com/blog/webauthn-public-key-credential-hints'
title: 'WebAuthn Public Key Credential / User-Agent Hints'
description: 'Learn about WebAuthn Public Key Credential Hints / User-Agent Hints, their availability, how they can be used and what limitations and recommendations exist.'
lang: 'en'
author: 'Vincent Delitz'
date: '2024-10-11T10:30:07.952Z'
lastModified: '2026-03-25T10:00:45.412Z'
keywords: 'webauthn public key credential hint, webauthn public key credential hints, webauthn user-agent hint, webauthn user-agent hints, webauthn hints, webauthn hint, passkey hint, passkey hints'
category: 'WebAuthn Know-How'
---

# WebAuthn Public Key Credential / User-Agent Hints

## Key Facts

- **WebAuthn Level 3** introduced three credential hint types, `security-key`,
  `client-device` and `hybrid`, providing browsers non-binding guidance on which
  authenticator type to prioritize during authentication.
- **Chrome version 128** was the first browser to support credential hints; Edge followed
  at the same version, Safari has planned support and Firefox has no confirmed timeline.
- When hints contradict `authenticatorAttachment`, **hints take precedence**, giving
  developers more flexibility than the previous strict platform or cross-platform binary
  restriction.
- **Windows 11** ignores credential hints entirely because Windows Hello controls the
  passkey authentication UI, overriding Chrome and Edge hint support including for
  passkeys synced from Google Password Manager.
- As of October 2024, explicitly setting **`authenticatorAttachment`** in Chrome overrides
  credential hints, making hints effective only when authenticatorAttachment is left
  unspecified.

## 1. Introduction

WebAuthn and passkeys are getting strong momentum and more and more adoption. Also, from a
technical point of view, the WebAuthn standard is quickly evolving. **WebAuthn public key
credentials hints (also called User-agent Hints)** are the latest addition to the Web
Authentication API, aiming to enhance the way developers implement passkey authentication
in their applications.

In this article, we'll answer the following questions?

- **What are WebAuth Public Key Credential Hints?**
- **Why do you need WebAuthn Public Key Credential Hints?**
- **How do WebAuthn Public Key Credential Hints work?**
- **What are the limitations and recommended cases of WebAuthn Public Key Credential Hints
  for your projects?**

Let’s start by looking at the motivation first.

## 2. Motivation for Credential Hints in Passkeys

Nowadays, there are different places where you can create and store a passkey:

- Third-party [password manager](https://www.corbado.com/blog/passkeys-vs-password-managers) (e.g.
  [1Password](https://www.corbado.com/blog/1password-passkeys-best-practices-analysis),
  [Dashlane](https://www.corbado.com/blog/dashlane-passkeys),
  [Bitwarden](https://www.corbado.com/blog/passkey-analysis-bitwarden-developer-survey-2024),
  [KeePassXC](https://www.corbado.com/blog/keepassxc-passkeys))
- [Google Password Manager](https://www.corbado.com/blog/how-to-use-google-password-manager) / Chrome Profile
- [iCloud Keychain](https://www.corbado.com/glossary/icloud-keychain) /
  [Apple Passwords](https://www.corbado.com/blog/how-to-use-apple-passwords)
- [Windows Hello](https://www.corbado.com/glossary/windows-hello)
- Another smartphone (iOS, [Android](https://www.corbado.com/blog/how-to-enable-passkeys-android)) or tablet
  (iPadOS, [Android](https://www.corbado.com/blog/how-to-enable-passkeys-android))
- Hardware [security key](https://www.corbado.com/glossary/security-key) (e.g. [YubiKey](https://www.corbado.com/glossary/yubikey))

For the user, this can offer flexibility and freedom of choice. However, some applications
and scenarios require to restrict some of these options, e.g. if you want to only allow
[hardware security keys](https://www.corbado.com/blog/best-fido2-hardware-security-keys) due to increased
security requirements.

To influence that [passkey creation](https://www.corbado.com/blog/passkey-creation-best-practices) and storage,
we had the `authenticatorAttachment` property.

## 3. What is authenticatorAttachment?

The `authenticatorAttachment` allows relying parties to restrict where the passkey can be
created on.

### 3.1 platform

`platform` indicates an [authenticator](https://www.corbado.com/glossary/authenticator) that is built into the
device running WebAuthn. WebAuthn communicates with it using transport methods specific to
that platform, such as platform-specific APIs. A public key credential linked to a
[platform authenticator](https://www.corbado.com/glossary/platform-authenticator) is called a platform
credentials. From the list above, the following credential managers / locations could
store platform credentials:

- Third-party [password manager](https://www.corbado.com/blog/passkeys-vs-password-managers) (e.g.
  [1Password](https://www.corbado.com/blog/1password-passkeys-best-practices-analysis),
  [Dashlane](https://www.corbado.com/blog/dashlane-passkeys),
  [Bitwarden](https://www.corbado.com/blog/passkey-analysis-bitwarden-developer-survey-2024),
  [KeePassXC](https://www.corbado.com/blog/keepassxc-passkeys))
- [Google Password Manager](https://www.corbado.com/blog/how-to-use-google-password-manager) / Chrome Profile
- [iCloud Keychain](https://www.corbado.com/glossary/icloud-keychain) /
  [Apple Passwords](https://www.corbado.com/blog/how-to-use-apple-passwords)
- [Windows Hello](https://www.corbado.com/glossary/windows-hello)

**Windows 11 and Chrome:**

![windows platform](https://www.corbado.com/website-assets/windows_platform_4f37a3c043.png)

macOS 15 (Sequoia) and Chrome:

![macos chrome platform](https://www.corbado.com/website-assets/macos_chrome_platform_1f43ad0ce3.png)

When clicking on Cancel, the following modal appears:

![macos chrome platform cancel](https://www.corbado.com/website-assets/macos_chrome_platform_cancel_fe9ba82f1c.png)

**macOS 15 (Sequoia) and Safari:**

![macos safari platform](https://www.corbado.com/website-assets/macos_safari_platform_3120aa89e3.png)

### 3.2 cross-platform

`cross-platform` indicates an [authenticator](https://www.corbado.com/glossary/authenticator) that is external to
the device running WebAuthn (roaming [authenticator](https://www.corbado.com/glossary/authenticator)) because it
can be used across multiple devices. WebAuthn interacts with it using cross-platform
transport protocols like Bluetooth or NFC. A public key credential associated with a
roaming authenticator is called a roaming credential. From the list above, the following
credential managers / locations could store cross-platform credentials:

- Another smartphone (iOS, [Android](https://www.corbado.com/blog/how-to-enable-passkeys-android)) or tablet
  (iPadOS, Android)
- Hardware [security key](https://www.corbado.com/glossary/security-key) (e.g. [YubiKey](https://www.corbado.com/glossary/yubikey))

**Windows 11 and Chrome:**

![windows cross platform](https://www.corbado.com/website-assets/windows_cross_platform_d9103bdb1b.png)

**macOS 15 (Sequoia) and Chrome:**

![macos chrome cross platform](https://www.corbado.com/website-assets/macos_chrome_cross_platform_42d0696186.png)

**macOS 15 (Sequoia) and Safari:**

![macos safari cross platform](https://www.corbado.com/website-assets/macos_safari_cross_platform_bdc76f2bd1.png)

### 3.3 Not specified

**Not specified** indicates that either a
[platform authenticator](https://www.corbado.com/glossary/platform-authenticator) or a cross-platform
authenticator can be used. Here, the user can choose where they would like to store the
passkeys.

**Windows 11 and Chrome:**

![windows not specified](https://www.corbado.com/website-assets/windows_not_specified_7ac230a492.png)

**macOS 15 (Sequoia) and Chrome:**

![macos chrome not specified](https://www.corbado.com/website-assets/macos_chrome_not_specified_74d62875f7.png)

**macOS 15 (Sequoia) and Safari:**

![macos safari not specified](https://www.corbado.com/website-assets/macos_safari_not_specified_c790ff1ca1.png)

When clicking on Cancel, the following modal appears:

![macos chrome not specified cancel](https://www.corbado.com/website-assets/macos_chrome_not_specified_cancel_a8990296f4.png)

authenticatorAttachment was used for quite some time. However, it was also inflexible in
regard to new developments like Cross-Device Authentication (via QR codes and Bluetooth).
Here, a passkey is stored also e.g. in
[Google Password](https://www.corbado.com/blog/how-to-use-google-password-manager) Manager (platform credential)
but triggered with `cross-platform` by the [relying party](https://www.corbado.com/glossary/relying-party).
Besides that, the control of a [relying party](https://www.corbado.com/glossary/relying-party) to influence the
kind of passkey that should be used in a login (not register) ceremony could only be done
by modifying the `transports` value of a credential.

That’s where WebAuthn Public Key Credential Hints come into play.

## 4. What Are WebAuthn Public Key Credential Hints?

WebAuthn public key credential hints are a new parameter introduced in the Web
Authentication API (officially in [WebAuthn Level 3](https://www.corbado.com/blog/passkeys-prf-webauthn)). They
provide guidance to browsers about the type of authenticator a user is likely to use
during the authentication process. This helps in delivering a more streamlined and
intuitive user experience by focusing the browser's UI on the most relevant options.

**The Three Types of Hints**

The hints come in three types:

1. **`security-key`**: Indicates that the user is expected to use a hardware
   [security key](https://www.corbado.com/glossary/security-key) (e.g. [YubiKey](https://www.corbado.com/glossary/yubikey)).
2. **`client-device`**: Suggests that the user will use a
   [platform authenticator](https://www.corbado.com/glossary/platform-authenticator) attached to the client
   device ( like Touch ID on macOS, [Face ID](https://www.corbado.com/faq/is-face-id-passkey) on
   [iOS](https://www.corbado.com/blog/webauthn-errors) or [Windows Hello](https://www.corbado.com/glossary/windows-hello) on Windows).
3. **`hybrid`**: Implies that the user might use a smartphone or table for cross-device
   authentication via [QR code](https://www.corbado.com/blog/qr-code-login-authentication) and Bluetooth.

These hints are not strict requirements from the [relying party](https://www.corbado.com/glossary/relying-party)
but serve as guidance to enhance the user experience as hints to the browser.

### 4.1 security-key

In the following, you see screenshots for macOS Sequoia (Edge + Chrome) and Windows 10
(Chrome) with authenticatorAttachment not specified and WebAuthn
[User-agent](https://www.corbado.com/blog/client-hints-user-agent-chrome-safari-firefox) Hint set to
`security-key`.

#### 4.1.1 macOS Sequoia & Edge

![macos edge security key hint](https://www.corbado.com/website-assets/macos_edge_security_key_hint_9c6c4f27eb.png)

#### 4.1.2 macOS Sequoia & Chrome

![macos chrome security key hint](https://www.corbado.com/website-assets/macos_chrome_security_key_hint_797985e0fe.png)

#### 4.1.3 Windows 10 & Chrome

Here, we see another limitation, that the `security-key` hint is not respected on Windows
10, at least not directly. The flow is basically the same as for the `client-device` hint.

![windows 10 chrome security key hint 1](https://www.corbado.com/website-assets/windows_10_chrome_security_key_hint_1_683c5a5e43.jpeg)

When clicking on Cancel, the following modal appears:

![windows 10 chrome security key hint 2](https://www.corbado.com/website-assets/windows_10_chrome_security_key_hint_2_e38d86bf60.jpeg)

### 4.2 client-device

In the following, you see screenshots for macOS Sequoia (Edge + Chrome) and Windows 10
(Chrome) with authenticatorAttachment not specified and WebAuthn
[User-agent](https://www.corbado.com/blog/client-hints-user-agent-chrome-safari-firefox) Hint set to
`client-device`.

#### 4.2.1 macOS Sequoia & Edge

![macos edge client device hint 1](https://www.corbado.com/website-assets/macos_edge_client_device_hint_1_cfbc01e9bf.png)

When clicking on Cancel, the following modal appears:

![macos edge client device hint 2](https://www.corbado.com/website-assets/macos_edge_client_device_hint_2_c5770ea67e.png)

#### 4.2.2 macOS Sequoia & Chrome

![macos chrome client device hint 1](https://www.corbado.com/website-assets/macos_chrome_client_device_hint_1_b2eb3faa3d.png)

When clicking on Cancel, the following modal appears:

![macos chrome client device hint 2](https://www.corbado.com/website-assets/macos_chrome_client_device_hint_2_0f29636476.png)

#### 4.2.3 Windows 10 & Chrome

![windows 10 chrome security key hint 1](https://www.corbado.com/website-assets/windows_10_chrome_security_key_hint_1_683c5a5e43.jpeg)

When clicking on Cancel, the following modal appears:

![windows 10 chrome security key hint 2](https://www.corbado.com/website-assets/windows_10_chrome_security_key_hint_2_e38d86bf60.jpeg)

### 4.3 hybrid

In the following, you see screenshots for macOS Sequoia (Edge + Chrome) and Windows 10
(Chrome) with authenticatorAttachment not specified and WebAuthn
[User-agent](https://www.corbado.com/blog/client-hints-user-agent-chrome-safari-firefox) Hint set to `hybrid`.

#### 4.3.1 macOS Sequoia & Edge

![macos edge hybrid hint](https://www.corbado.com/website-assets/macos_edge_hybrid_hint_ee60f2a080.png)

#### 4.3.2 macOS Sequoia & Chrome

![macos chrome hybrid hint](https://www.corbado.com/website-assets/macos_chrome_hybrid_hint_99550c23d0.png)

#### 4.3.3 Windows 10 & Chrome

![windows 10 chrome hybrid hint](https://www.corbado.com/website-assets/windows_10_chrome_hybrid_hint_41ea4fea2f.jpeg)

## 5. How Do WebAuthn Public Key Credential Hints Work?

With the introduction of hints, developers can now provide an array of preferences in
order of decreasing priority, offering more flexibility.

### 5.1 Example for Security-Key Hint

The code snippet below tells the browser that the user is likely to authenticate using a
hardware security key, focusing the UI accordingly.

For compatibility with older user agents, when this hint is used in
[PublicKeyCredentialCreationOptions](https://www.corbado.com/glossary/publickeycredentialcreationoptions), the
authenticatorAttachment should be set to `cross-platform`.

```javascript
const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    hints: ['security-key'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});
```

The `security` hint is particularly valuable in high-assurance cases where the website /
relying party only wants to allow
[hardware security keys](https://www.corbado.com/blog/best-fido2-hardware-security-keys) and pushes the user in
this direction.

### 5.2 Example for Client-Device Hint

In this example, the hint suggests that the user might use the current device’s built-in
platform authenticator.

For compatibility with older user agents, when this hint is used in
[PublicKeyCredentialCreationOptions](https://www.corbado.com/glossary/publickeycredentialcreationoptions), the
authenticatorAttachment should be set to `platform`.

```javascript
const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    residentKey: true,
    hints: ['client-device'],
    authenticatorSelection: {
      authenticatorAttachment: 'platform'
    }
  }
});
```

Setting the `client-device` hint is beneficial if there are multiple passkeys associated
with a user account and some of them might be available on the device logging in, whereas
others are stored on different devices. If the system (
[passkey intelligence](https://docs.corbado.com/corbado-connect/features/passkey-intelligence))
detects that the user trying to log in has with high probability a local passkey
available, then this hint can be set in the
[PublicKeyCredentialRequestOptions](https://www.corbado.com/glossary/publickeycredentialrequestoptions) saving
the user one click to select the right passkey.

### 5.3 Example for Hybrid Hint

In this example, the hint suggests that the user might use a smartphone or a similar
device for authentication.

For compatibility with older user agents, when this hint is used in
[PublicKeyCredentialCreationOptions](https://www.corbado.com/glossary/publickeycredentialcreationoptions), the
authenticatorAttachment should be set to `cross-platform`.

```javascript
const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    residentKey: true,
    hints: ['hybrid'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});
```

The `hybrid` hint can be helpful if the user has multiple keys and the system
([passkey intelligence](https://docs.corbado.com/corbado-connect/features/passkey-intelligence))
detects that on the current device, there is probably no local passkey available. To
improve the UX and save one click, you can set this WebAuthn User-agent hint and directly
prompt the user for cross-device authentication (via
[QR code](https://www.corbado.com/blog/qr-code-login-authentication) and Bluetooth). Moreover, if you try to
build a
[mobile-first passkey](https://www.corbado.com/blog/webauthn-cross-device-authentication-passkeys-mobile-first)
system, then setting this hint makes a lot of sense.

To play around yourself with the different options, we recommend to take a look at the
[Passkeys Debugger](https://www.passkeys-debugger.io).

## 6. Priorities

It's crucial to understand how WebAuthn Public Key Credential Hints interact with other
WebAuthn parameters like authenticatorAttachment and credential transports.

### 6.1 Non-Binding Guidance

Firstly, it's important to note that these **hints are not strict requirements**. They do
not bind the user-agent ( browser) but serve as guidance to provide the best experience by
leveraging contextual information you have about the request. This means browsers may
choose to consider the hints but are not obligated to follow them strictly.

### 6.2 Order Matters

Hints are provided as an array in order of **decreasing preference**. This order
determines how the browser should prioritize them:

- **First Hint Takes Precedence**: If two hints are contradictory, the browser gives
  priority to the first one.
- **Overlapping Hints**: If a more specific hint might not be recognized by all browsers,
  you can include less specific ones afterward for broader compatibility.
- **Duplicate Hints**: If the same hint appears more than once, any subsequent appearances
  are ignored.

**Example:**

`hints: ['security-key', 'hybrid', 'client-device']`

In this array:

1. The browser first prioritizes security-key.
2. If not applicable, it considers hybrid.
3. Lastly, it looks at client-device (platform [authenticators](https://www.corbado.com/glossary/authenticator)
   on the client device).

### 6.3 Hints vs. Other Parameters

Hints can **contradict** information contained in authenticatorAttachment and credential
transports. When this occurs, **hints take precedence**. This offers more flexibility
compared to the previous strict usage of authenticatorAttachment, which limited the
authenticator to either `platform` or `cross-platform`.

**Example with Contradictory Parameters:**

```javascript
const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    hints: ['hybrid'],
    authenticatorSelection: {
      authenticatorAttachment: 'platform' // Contradicts the hint
    }
  }
});
```

In this case:

- **Hint**: Suggests a preference for hybrid [authenticators](https://www.corbado.com/glossary/authenticator).
- **authenticatorAttachment**: Specifies `platform`, which normally limits
  [authenticators](https://www.corbado.com/glossary/authenticator) to the client device.
- **Outcome**: The browser prioritizes the hint over authenticatorAttachment, focusing on
  hybrid options.

## 7. Browser Support

Currently, **WebAuthn public key credential hints** are only available in **Chrome (since
version 128)**. As of now, **Edge** and **Safari** have indicated plans to integrate this
feature, while **Firefox** has not yet confirmed its release timeline.

| **Browser**  | **Chrome**                                                                | **Edge**                                                                  | **Safari**                                                | **Firefox** |
| ------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------- | ----------- |
| Availability | ✅ [since version 128](https://chromestatus.com/feature/5145737733341184) | ✅ [since version 128](https://chromestatus.com/feature/5145737733341184) | [Planned](https://bugs.webkit.org/show_bug.cgi?id=278481) | n/a         |

It is important to remember that in **Chrome**, the authenticatorAttachment parameter
continues to be respected for now. This means that today the authenticatorAttachment is
the decisive factor, no matter which hint is set. However, we expect that in future Chrome
versions, the public key credential hints will be becoming the preferred and only
approach.

### 7.1 Special Case: Windows 11 and Chrome / Edge

Even though the latest Chrome version support WebAuthn User-agent Hints, these hints are
not respected by [Windows 11](https://www.corbado.com/blog/passkeys-windows-11) and Windows Hello / Windows
Security. The underlying reason is that the UI is controlled by the operating system
(Windows Hello / Windows Security) itself.

Moreover, a passkey which is stored in **Google Password Manager and synced to Windows 11,
the WebAuthn User-agent Hints are not respected**, as the final local authentication on
[Windows 11](https://www.corbado.com/blog/passkeys-windows-11) happens with Windows Hello / Windows Security.
With the upcoming sync of passkeys on [Windows 11](https://www.corbado.com/blog/passkeys-windows-11) via
Microsoft accounts, we also expect improvements for Windows 11 and WebAuthn User-agent
Hints.

### 7.2 Special Case: Windows 10 and Chrome / Edge

On **Windows 10, WebAuthn User-agent Hints are respected though**, as the WebAuthn UI is
handled by Chrome and not by Windows Hello / Windows Security. However during our tests,
we didn't see an effect for `security-key`. When this hint was set, the flow looked liked
the one for `client-device`.

## 8. Recommendations for Public Key Credential Hints

WebAuthn public key credential (user-agent) hints bring a range of benefits to both
developers and users. The feature is still new and not rolled out to all browsers and
operating systems yet (as of October 2024).

It’s important to be aware of the **current limitations** that especially come with
Windows 11. **In Windows 11, the passkey UI is handled by Windows Hello (Windows Hello
security modal) and this currently rules over Chrome’s / Edge’s support for WebAuthn
User-agent hints. This also applies to passkeys being synced from Google Password Manager
to Windows (here, hints also have no effect yet).**

This means WebAuthn public key credential hints really work only on macOS and Windows 10
(from the major desktop operating systems).

Moreover, as of October 2024, even if Chrome / Edge is used on these operating systems, if
the authenticatorAttachment is set, then this also rules over the WebAuthn User-agent
hints (as
[stated by Google](https://developer.chrome.com/blog/passkeys-updates-chrome-129)).

From a use case perspective, we see the following recommended use cases to get the most
value of this new feature.

### 8.1 Use Hints in Login Processes to Reduce Clicks

When building your backend and passkey intelligence, try to include the right usage of
public key credential hints to facilitate the login and save the user of unnecessary
clicks. For example, if your system detects that a user logs in on a device where probably
a local passkey is available, use the `client-device` hint.

If the user accesses the website from a new device and your
[passkey intelligence](https://docs.corbado.com/corbado-connect/features/passkey-intelligence)
knows that a passkey might be available at a mobile device of the user, set the hint to
`hybrid`, so that the user can quickly scan the
[QR code](https://www.corbado.com/blog/qr-code-login-authentication) and make use of the hybrid passkey.

The main goal here is to provide a more seamless and intuitive user experience. By guiding
browsers on which authenticators are likely to be used, developers can reduce user
confusion and friction during the login process. Instead of users being overwhelmed with
unnecessary authentication options, hints allow browsers to focus on the most relevant
choices, which leads to a faster, more straightforward experience.

### 8.2 Use Security-Key Hint as High-Assurance Enterprise or Government

High-assurance enterprises or governmental organizations that have standardized on
[hardware security keys](https://www.corbado.com/blog/best-fido2-hardware-security-keys) for user authentication
will find passkey credential hints particularly useful. By using the `security-key` hint,
they can ensure that browsers prominently display the hardware security key option.

This is especially useful for large organizations where employees have been issued
hardware security keys and where other authentication methods (such as platform
authenticators) are not permitted. The `security-key` hint enables enterprises to lock
down their authentication flows without limiting their flexibility for future
improvements.

### 8.3 Use Hybrid Hint for Mobile-First Applications

The `hybrid` hint shines in scenarios where cross-device authentication and thus a
mobile-first approach is desired or when users frequently move between devices or
platforms.

An example of this use case would be a consumer-facing app that anticipates most of its
users will use their smartphones for authentication, either through biometric methods or
web-based authenticator apps (mobile-first passkeys). By specifying `hybrid` as a hint,
developers ensure that the browser's UI encourages smartphone use, improving convenience
and accessibility.

## 9. Conclusion

WebAuthn public key credential hints offer a flexible way to enhance the user experience
during passkey authentication. Let’s revisit the questions from the introduction with the
insights we've gathered:

1. **What are WebAuthn Public Key Credential Hints?**

    They are optional suggestions provided by the website / app to guide clients on the
    most likely authentication method a user will use – whether it's a hardware security
    key, platform authenticator, or a hybrid solution like cross-device authentication.

2. **Why do you need WebAuthn Public Key Credential Hints?**

    They streamline the authentication process by narrowing down the options presented to
    users, reducing unnecessary friction / clicks and improving the overall experience.

3. **How do WebAuthn Public Key Credential Hints work?**

    Developers specify hints such as `security-key`, `client-device`, or `hybrid` based on
    the context, allowing browsers to prioritize the relevant authentication method for
    the user. While these hints aren't strict requirements, they help optimize the UI flow
    during authentication.

4. **What are the limitations and recommended use cases?**

    Currently, full support for these hints is limited to Chrome and Edge, with other
    browsers and operating systems like Windows 11 showing varying levels of
    compatibility. The most effective use cases include improving login UX, enforcing
    hardware security key usage in high-security environments, and enabling cross-device
    authentication in mobile-first applications.

In conclusion, WebAuthn Public Key Credential Hints allow developers to create more
intuitive,
[user-friendly authentication](https://www.corbado.com/faq/passkey-user-experience-benefits-non-technical-audience)
processes by guiding browsers to the most appropriate options for each user scenario.
While still evolving, this feature can significantly enhance both security and user
experience in passkey implementations.

## Frequently Asked Questions

### How can I use WebAuthn credential hints to reduce friction for returning users during login?

Set the `client-device` hint when your passkey intelligence detects a local passkey is
likely available on the signing-in device, directing the browser straight to the platform
authenticator and saving the user one click. Conversely, set the `hybrid` hint when no
local passkey is detected so the user is prompted immediately for cross-device
authentication via QR code and Bluetooth.

### What is the difference between WebAuthn credential hints and authenticatorAttachment, and which wins when they conflict?

The `authenticatorAttachment` parameter strictly limits the authenticator type to either
`platform` or `cross-platform`, while credential hints are non-binding suggestions that
guide browser UI without enforcing hard restrictions. When both are set and conflict,
hints are designed to take precedence, but as of October 2024 Chrome still respects
`authenticatorAttachment` when it is explicitly defined, so omitting it is currently
necessary for hints to have effect.

### Why should a high-assurance enterprise use the security-key credential hint rather than just setting authenticatorAttachment to cross-platform?

The `security-key` hint directs the browser UI to prominently display the hardware
security key option, which is valuable for organizations that have standardized on devices
like YubiKeys and want to steer employees toward that method. Unlike `cross-platform`, the
`security-key` hint also distinguishes hardware key flows from smartphone hybrid flows,
preserving flexibility for future authentication improvements without loosening security
policy.

### How does hint ordering work when I pass multiple WebAuthn credential hints in an array?

Hints are evaluated in decreasing order of preference, so the browser prioritizes the
first hint and falls back to subsequent ones if the first is not applicable. Contradictory
hints resolve in favor of the first entry, and any duplicate hints after their first
appearance are ignored entirely.