Setup

Passkey Login uses a Relying Party (RP) to tie passkeys to your apps. Each platform you target (Web, Android, iOS / macOS) needs a configuration file declaring your app under the RP. Platform authenticators validate the RP association against these files before any WebAuthn ceremony.

Hosting the configuration files

Two ways to set up the RP:

Shared with the Breez ecosystem (Breez-hosted). A passkey registered in one Breez-registered app works in every other Breez-registered app on the same device, with no re-registration. Contact us to register your app, then pass PasskeyProvider.BREEZ_RP_ID as your rpId.
Scoped to your ecosystem (self-hosted). A passkey registered against your RP works across the apps and web origins you list in your configuration files. You host the well-known files yourself on an HTTPS domain you control. Pass that domain as your rpId (for example, "<your-rp-domain>").

Same code paths in either case; only the rpId value and who hosts the JSON differs.

Path: /.well-known/webauthn

{
  "related_origins": [
    "https://keys.breez.technology",
    "https://your-app.example.com"
  ]
}

Requirements: Chrome 116+, Safari 18+, Edge 116+. HTTPS required (localhost exempt during development).

Firefox does not implement Related Origins. Its users register fresh on each origin. For multi-domain support, host a separate RP ID per domain.

Chrome and Edge cap the number of distinct origins in related_origins (around 5 per RP). For larger app families, partition into multiple RP IDs.

Browsers cache .well-known/webauthn aggressively. Adding or removing an origin takes effect only after the cache TTL expires.

Android: Asset Links

Path: /.well-known/assetlinks.json

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.yourapp",
      "sha256_cert_fingerprints": [
        "B6:16:AD:FE:C5:C6:D3:4C:93:01:5B:4A:79:20:21:4E:62:43:AB:29:28:EE:34:9A:F2:46:55:4B:54:FC:42:DF"
      ]
    }
  }
]

Replace com.example.yourapp with your application's package name and the fingerprint with your app's signing certificate SHA256. See the Digital Asset Links documentation and Credential Manager prerequisites.

Requirements: Android 9+ (API 28) with Google Play Services, or Android 14+ (API 34) with any compatible authenticator. compileSdkVersion must be at least 34 (required by the androidx.credentials library, not the device).

iOS / macOS: Apple App Site Association

Path: /.well-known/apple-app-site-association

{
  "webcredentials": {
    "apps": [
      "TEAMID.com.example.yourapp"
    ]
  }
}

Replace TEAMID with your Apple Developer Team ID and com.example.yourapp with your bundle identifier. Your app must also declare the Associated Domains capability in Xcode (Signing & Capabilities, then Associated Domains, then add webcredentials:<your-rp-domain>).

iOS / macOS: Associated Domains entitlement required

Without the Associated Domains entitlement declared in Xcode, passkey operations on iOS / macOS fail with a configuration error, even when

PasskeyClient.check_availabilityPasskeyClient.check_availabilityPasskeyClient.checkAvailabilityPasskeyClient.checkAvailabilityPasskeyClient.checkAvailabilityPasskeyClient.checkAvailabilityPasskeyClient.checkAvailabilityPasskeyClient.CheckAvailabilityPasskeyClient.CheckAvailability

returns

PasskeyAvailability::AvailablePasskeyAvailability.AVAILABLEPasskeyAvailability.availablePasskeyAvailability.AvailablePasskeyAvailability.AvailablePasskeyAvailability.AvailablePasskeyAvailability.AvailablePasskeyAvailabilityAvailablePasskeyAvailability.Available

iOS / macOS: Expo Managed Workflow

If you're using Expo, the Breez SDK plugin can configure the Associated Domains entitlement automatically. See the React Native/Expo installation guide for details on the enablePasskey option.

Requirements: iOS 18.0+, macOS 15.0+.

Keyboard shortcuts

Breez SDK - Spark