Web Bluetooth API & Passkeys

Passkeys are the new login standard in the web. One of passkey’s core features is Cross-Device Authentication (CDA) via Bluetooth and QR Codes. In this context, another web API becomes important: the Web Bluetooth API.

By enabling web apps to interact directly with Bluetooth devices, the Web Bluetooth API plays a crucial role in ensuring secure and efficient authentication processes (especially for CDA).

This blog post will present the workings of the Web Bluetooth API and explore the implications of Bluetooth detection for passkey authentication. We want to answer the following questions:

1. What is the Web Bluetooth API?
2. How to use the Web Bluetooth API?
3. Why is Bluetooth detection important for passkeys?

The Web Bluetooth API is a JavaScript interface that allows web apps to access and communicate with Bluetooth devices. It is part of the HTML5 standard and is supported by browsers like Chrome, Edge, and Opera. This API enables web apps to

• scan for nearby Bluetooth Low Energy (BLE) devices
• request permission to pair
• exchange data using the Generic Attribute Profile (GATT) protocol.

There are three key functions of the Web Bluetooth API.

getAvailability() returns a promise that resolves to a Boolean indicating whether the user agent can support Bluetooth (so the device has a Bluetooth module). Some user agents let the user configure an option that specifies what value is returned by this method.

navigator.bluetooth.getAvailability().then((available) => {
 
    if (available) {
        console.log("This device supports Bluetooth!");
    } else {
        console.log("Doh! Bluetooth is not supported");
    }
});

Subscribe to our Passkeys Substack for the latest news, insights and strategies.

Subscribe

getDevices() returns a promise that resolves to an array of BluetoothDevices the origin is allowed to access (including those that are out of range and powered off). Permission is obtained via previous calls to Bluetooth.requestDevice().

navigator.bluetooth.getDevices().then((devices) => {
    devices.forEach(
        device => {
            console.log('Device:', device.name);
        });
});

requestDevice() returns a promise to a BluetoothDevice object with specified options. If there is no chooser UI, this method returns the first device matching the criteria.

navigator.bluetooth.requestDevice({
    filters: [{
        services: ['battery_service']
    }]
}).then(
    device => {
        console.log('Device:', device.name);
    }).catch(error => {
    console.log('Error:', error);
});

Details and code snippets can be found here. Also find here the W3C standard for Web Bluetooth.

Become part of our Passkeys Community for updates and support.

Join

• HTTPS only: The Web Bluetooth API is available only in secure contexts (HTTPS), ensuring secure data transmission.
• User gesture required: Device discovery via navigator.bluetooth.requestDevice must be triggered by a user gesture, such as a touch or mouse click, for security reasons.

To check for the support of the Web Bluetooth API, you can do so via the following code:

if ('bluetooth' in navigator) {  
 // Web Bluetooth API is supported  
 console.log('Web Bluetooth is supported!');  
} else {  
 // Web Bluetooth API is not supported  
 console.log('Web Bluetooth is not supported!');  
}

How the specific functions are called is explained above.

The Web Bluetooth API offers several advantages for developers and users:

• Interactivity: Enables web apps to interact with Bluetooth devices without native apps or plugins.
• Enhanced User Experience: Allows access to device features and sensors of wireless devices like heart rate monitors or music controls.
• Security & Privacy: Users must grant permission for device access, which can be revoked at any time.

Despite its benefits, the Web Bluetooth API has limitations:

• No Support by Safari and Firefox: Not all browsers support the API. Notably, Safari and Firefox do not support it, which can impact a significant portion of users.
• Dependency on Device Capabilities: The API works only with compatible Bluetooth Low Energy (BLE) devices. Additionally, devices may not be discoverable due to factors like low battery or being out of range.
• Evolving Specification: As a draft specification, the Web Bluetooth API is subject to changes. Developers need to stay updated on the latest developments and browser compatibility.
• False Positives: The API can sometimes indicate Bluetooth support when it is not actually available.
• User-Controlled Availability: Users and browsers can disable Bluetooth permissions, causing getAvailability() to return false even if a Bluetooth adapter is present. This is controlled via the Permissions-Policy:Bluetooth. Similarly, even if getAvailability() returns true, the Bluetooth adapter may not be powered on, or users may deny permission to use the API when prompted.

Adoption of the Web Bluetooth API is still growing. As of June 2024, according to Can I Use, 76.53% of global users have devices with support for Web Bluetooth API.

However, the lack of support in Safari and Firefox remains a significant hurdle, impacting user experience on those browsers. Also, some of the features (e.g. Bluetooth.getDevices()) must be explicitly turned on by the user, which can be a challenge for using the API in the background.

Find the latest data on: https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API#browser_compatibility

There is one major reason why relying parties should know about the availability of Bluetooth, when they want to offer passkeys in their websites and applications.

One of the new, innovative features of passkeys is Cross-Device Authentication (CDA) – also known as hybrid authentication. This feature allows users to authenticate on one device (typically a desktop or laptop) using their mobile devices via QR codes and Bluetooth. This hybrid authentication method enhances security and convenience, providing a seamless user experience. Most non-technical users are nowadays accustomed to scanning QR codes, whether during the COVID pandemic for registration or via mobile-first messaging apps that later added desktop support (e.g., WhatsApp or Telegram).

Deciding on a CDA strategy is crucial at the beginning of any passkey project. The more you rely on CDA, the better the support and reliability of it needs to be. Thus, detecting Bluetooth availability on a device is essential.

However, not all devices have Bluetooth capabilities or may have Bluetooth turned off. For relying parties who offer passkeys, it's essential to detect Bluetooth availability to determine whether CDA can be used or if another fallback authentication method is necessary. The Web Bluetooth API provides a solution by enabling web apps to check Bluetooth availability on user devices.

Please bear in mind that CDA is not always stable, occasionally failing to connect without clear reasons. Moreover, due to the novelty of the API, sometimes wrong results are returned by the API.

The non-availability of Web Bluetooth API in Firefox and Safari is an issue, particularly for Firefox.

Safari is less of an issue because macOS devices, where CDA might be performed, have had built-in Bluetooth since early models. Additionally, iPhones running Safari have had Bluetooth built-in since their inception.

Though, Firefox is a significant issue as it is popular on Windows devices. If a user is on Firefox and wants to use CDA, the relying party cannot reliably determine if Bluetooth is available, as the Web Bluetooth API is not implemented. This might result in a poor user experience, with users potentially getting stuck at certain points without knowing what to do.

As we have seen, also in previous blogs, Windows devices are lagging behind in terms of passkey adoption (see State of Passkeys as well). Let’s take a look how common Bluetooth availability is.

Windows 10 does not have a strict Bluetooth requirement, but most modern laptops and desktops come with Bluetooth capabilities. However, the user might have it turned off, or it may not be available in some configurations, especially on custom-built desktops.

Windows 11, similar to Windows 10, does not mandate Bluetooth. However, the trend towards more integrated and modern hardware means that most Windows 11 compatible devices will likely have Bluetooth capabilities. Still, users can disable it, affecting CDA implementations.

In the following table you can see whether you can determine if a desktop device is Bluetooth-ready and thus can be used as a CDA client:

Keep in mind that even if your hardware is Bluetooth-ready, Bluetooth functionality might be turned off by the user. When Bluetooth is turned off, the user can still use CDA because the user can still opt-in to activate it, which works for Windows and Mac: macOS request to turn on Bluetooth

Windows 11 request to turn on Bluetooth

The Bluetooth availability information is especially interesting on Windows 10 and Windows 11, where Blueooth support is lower and there is a very high probability cross-device authentication will need to happen (in a passkey-based login). Recent macOS devices all have support for Bluetooth. These macOS devices have potentially also access to passkeys stored in the iCloud Keychains directly, so they are not of concern.

On Windows 10 and Windows 11: Use getAvailability() to find out if Bluetooth can work. In case the user has only non-Windows passkeys, you can immediately fall back to other authentication options.

In a situation where there are only hybrid passkeys available, triggering passkey authentication will not lead to a successful authentication, but rather a dead-end for the user. For all other browsers on Windows 10 and Windows 11, unfortunately, there is no other way to find out if there is support für CDA.

The Web Bluetooth API represents a powerful tool for enhancing passkey authentication through Bluetooth capabilities. By understanding and leveraging this API, developers can create more secure and user-friendly authentication methods. However, they must also navigate its limitations and ensure robust fallback mechanisms to maintain a seamless user experience across different browsers and devices.

With this blog post, we have given an answer of the three core questions:

1. What is the Web Bluetooth API? The Web Bluetooth API is a JavaScript interface allowing web apps to access and communicate with Bluetooth devices, facilitating secure interactions.
2. How to use the Web Bluetooth API? Use the Web Bluetooth API by calling functions like getAvailability(), getDevices() and requestDevice() to check Bluetooth support, list accessible devices, and request device pairing.
3. Why is Bluetooth detection for passkeys important? By integrating the Web Bluetooth API into your passkey implementation strategy, you can build a great passkey-based authentication solution that falls back to CDA only if there are devices that can detect Bluetooth support.

For more information regarding Web Bluetooth API and a collection of examples, please click here.