Passkey Authentication

Passkey authentication is fully local-first and the most secure of the auth methods that Jazz provides because keys are managed by the device/operating system itself.

#How it works

Passkey authentication is based on the Web Authentication API and uses familiar FaceID/TouchID flows that users already know how to use.

#Key benefits

• Most secure: Keys are managed by the device/OS
• User-friendly: Uses familiar biometric verification (FaceID/TouchID)
• Cross-device: Works across devices with the same biometric authentication
• No password management: Users don't need to remember or store anything
• Wide support: Available in most modern browsers and mobile platforms

#Implementation

Using passkeys in Jazz is as easy as this:

#React Native Setup

Passkey authentication on React Native requires the react-native-passkey library and domain configuration:

1. Install the peer dependency:

   npm install react-native-passkey

2. Configure your app's associated domains:

   • iOS: Add an Associated Domains entitlement with webcredentials:yourdomain.com and host an Apple App Site Association (AASA) file at https://yourdomain.com/.well-known/apple-app-site-association
   • Android: Host a Digital Asset Links file at https://yourdomain.com/.well-known/assetlinks.json

3. For React Native 0.76+ with New Architecture: The react-native-passkey library uses the legacy NativeModules bridge pattern. You need to disable bridgeless mode while keeping New Architecture enabled.

   Add this override to your AppDelegate.swift:

class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
  // ... existing methods ...

  override func bridgelessEnabled() -> Bool {
    return false
  }
}

See the react-native-passkey documentation for detailed setup instructions.

#Examples

You can try passkey authentication using our passkey example or the music player demo.

#When to use Passkeys

Passkeys are ideal when:

• Security is a top priority
• You want the most user-friendly authentication experience
• You're targeting modern browsers and devices
• You want to eliminate the risk of password-based attacks

#Limitations and considerations

• Requires hardware/OS support for biometric authentication
• Not supported in older browsers (see browser support below)
• Requires a fallback method for unsupported environments

#React Native Limitations

• Requires react-native-passkey peer dependency
• Passkeys require domain verification (AASA for iOS, assetlinks.json for Android)
• Not available in Expo Go (requires a development build)
• React Native 0.76+ with New Architecture requires disabling bridgeless mode (see setup instructions above)
• Android builds may hang at configureCMakeDebug with NDK 27.x - use NDK 28.2+ to avoid this

#Browser Support

Passkeys are supported in most modern browsers.

For older browsers, we recommend using passphrase authentication as a fallback.

#Additional resources

For more information about the Web Authentication API and passkeys:

• WebAuthn.io
• MDN Web Authentication API