> ## Documentation Index > Fetch the complete documentation index at: https://docs.prelude.so/llms.txt > Use this file to discover all available pages before exploring further. # Passkey > Implement passkey authentication with the Prelude mobile SDKs. This guide covers how to register passkeys, sign in with them, use them in a step-up, and manage them in your mobile application. Make sure you have [configured passkeys](https://docs.prelude.so/auth/documentation/integration-guide/passkey.md) on your backend before proceeding. Passkeys serve two roles in the SDK: * **Primary-factor sign-in**: the user signs in with only a passkey, with no OTP and no password. Driven by `loginWithPasskey`. Requires `login_enabled` in the passkey configuration. * **Step-up factor**: the user already has a session and proves a passkey to acquire a sensitive scope. Driven by `continueStepUpWithPasskey`. For the concepts (ceremony shape, security model, webhooks), see the [Passkey](https://docs.prelude.so/auth/documentation/passkey.md) page. Pick your platform once: tabs across this section stay in sync. ## Requirements Passkeys need a more recent OS version than the rest of the SDK, and the SDK version that added them: | Platform | SDK version | OS version | | - | - | - | | iOS | `PreludeAuth` 0.7.0 or later | iOS 16 or later | | Android | `so.prelude.android:auth-sdk` 0.7.1 or later | Android 9 (API 28) or later | | Flutter | `prelude_flutter_auth_sdk` 0.7.0 or later | iOS 16 or later, Android API 28 or later | | React Native | `@prelude.so/react-native-auth-sdk` 0.7.1 or later | iOS 16 or later, Android API 28 or later | On a device that cannot run a passkey ceremony, the passkey methods fail with a "passkey not supported" error (see [Errors](#errors)). Offer another sign-in method in that case. ## Platform setup Before any passkey ceremony, the operating system verifies that your app is associated with the relying-party host (the `rp_id` of your passkey configuration). The association has two sides, and both are required: the server authorizes the app, and the app declares the host. ### Authorize your apps in the passkey configuration Add your native apps to the passkey configuration with the Management API. Prelude then serves the association documents (`/.well-known/apple-app-site-association` and `/.well-known/assetlinks.json`) on your app's Prelude domain: `.session.prelude.dev`, or your [custom domain](https://docs.prelude.so/auth/documentation/domain-names.md). The operating system fetches these documents from the `rp_id` host. When your `rp_id` is your app's Prelude domain, nothing more is needed. When it is another host, serve the same two documents on that host yourself. ```bash theme={null} curl -X PUT https://api.prelude.dev/v2/session/apps/${APP_ID}/config/passkey \ -H "Authorization: Bearer ${MANAGEMENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "rp_id": "auth.example.com", "rp_name": "Example App", "allowed_origins": ["https://auth.example.com"], "login_enabled": true, "ios_app_ids": ["ABCDE12345.com.example.app"], "android_apps": [ { "package_name": "com.example.app", "sha256_cert_fingerprints": [ "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5" ] } ] }' ``` | Field | Description | | - | - | | `ios_app_ids` | iOS app identifiers, each in the form `.`. | | `android_apps` | Android apps, each with its `package_name` and the SHA-256 fingerprints of its signing certificates (colon-separated hex, as printed by `keytool` or the Play Console). | > [!WARNING] > > This request replaces the passkey configuration. It is not a partial update. If your app already has a passkey configuration, read it first with `GET` on the same URL, then send every field again with its current value: `rp_id`, `rp_name`, `allowed_origins`, `user_verification`, `attestation_preference`, and `granted_scopes`. A field that you omit goes back to its default, and `granted_scopes` becomes empty. Changing `rp_id` breaks the passkeys that are already registered. See [Passkey Authentication](https://docs.prelude.so/auth/documentation/integration-guide/passkey.md) for all fields. Only `ios_app_ids`, `android_apps`, `login_enabled`, `aaguid_allowlist`, and `aaguid_blocklist` keep their stored value when you omit them. > [!NOTE] > > Add the fingerprint of every certificate that signs a build your users install. A debug build and a Play Store build are usually signed with different certificates. ### Declare the relying-party host in your app > [tab] iOS > > Add the Associated Domains capability to your app target, with one entry for the relying-party host: > > ``` > webcredentials:auth.example.com > ``` > [tab] Android > > The SDK references the Credential Manager `compileOnly`, so apps that skip passkeys pull no extra dependency. Add it to your module's `build.gradle.kts`: > > ```kotlin theme={null} > dependencies { > implementation("androidx.credentials:credentials:1.5.0") > // Google Password Manager provider, required below API 34: > implementation("androidx.credentials:credentials-play-services-auth:1.5.0") > } > ``` > > Then declare the Digital Asset Links statement under `` in `AndroidManifest.xml`: > > ```xml theme={null} > android:name="asset_statements" > android:resource="@string/asset_statements" /> > ``` > > ```xml theme={null} > > > [{\"include\":\"https://auth.example.com/.well-known/assetlinks.json\"}] > > ``` > > With only the server side in place, registration and login fail with `RP ID cannot be validated`. > [tab] Flutter > > * **iOS**: add the Associated Domains capability to the Runner target, with the entry `webcredentials:auth.example.com`. > * **Android**: add the Credential Manager to `android/app/build.gradle.kts` (the play-services provider is required below API 34): > > ```kotlin theme={null} > dependencies { > implementation("androidx.credentials:credentials:1.5.0") > implementation("androidx.credentials:credentials-play-services-auth:1.5.0") > } > ``` > > Then declare the Digital Asset Links statement under `` in `android/app/src/main/AndroidManifest.xml`: > > ```xml theme={null} > android:name="asset_statements" > android:resource="@string/asset_statements" /> > ``` > > ```xml theme={null} > > > [{\"include\":\"https://auth.example.com/.well-known/assetlinks.json\"}] > > ``` > > On Android, passkey calls need a foreground Activity. A call made while the Flutter engine is attached to no Activity throws `InvalidConfigurationException`. > [tab] React Native > > Add the relying-party host to the config plugin in `expo.plugins`: > > ```jsonc theme={null} > ["@prelude.so/react-native-auth-sdk", { "passkeyDomain": "auth.example.com" }] > ``` > > `expo prebuild` then adds the `webcredentials:auth.example.com` associated domain on iOS. On Android it adds the Credential Manager dependencies and the Digital Asset Links `asset_statements` meta-data. Combine `passkeyDomain` with `scheme` when you also use [social login](https://docs.prelude.so/auth/documentation/frontend-sdks/mobile/social-login.md). > > Without `prebuild` (a committed `ios/` or `android/` directory), apply the steps from the iOS and Android tabs by hand. ## Register a passkey A passkey is never the first credential of a user. Registration runs inside an authenticated session and requires the `prld:passkey:write` scope, which a [step-up](https://docs.prelude.so/auth/documentation/frontend-sdks/mobile/step-up.md) grants. Complete the step-up first, then register. > [!WARNING] > > The step-up that grants `prld:passkey:write` must use the grant mode `session-bound` or `profile-bound`. Registration verifies the scope against the session, so a `single-use` grant is not honored. > [tab] iOS > > ```swift theme={null} > import PreludeAuth > > let challenge = try await client.requestStepUp(scope: "prld:passkey:write") > try await client.sendStepUpOTP(challenge) > try await client.submitStepUpOTP(challenge, code: codeFromUser) > > do { > let result = try await client.registerPasskey( > RegisterPasskeyOptions( > username: "user@example.com", // shown by the authenticator > displayName: "User", // optional, defaults to username > nickname: "iPhone" // optional, server-side label > ) > ) > if result.alreadyRegistered { > // This authenticator was already registered for the user. > } > } catch PreludeAuthError.cancelled { > // User dismissed the system sheet — not an error. > } catch PreludeAuthError.insufficientScope { > // Session does not hold prld:passkey:write — run the step-up first. > } catch PreludeAuthError.passkeyNotSupported { > // Device cannot run a passkey ceremony. > } catch PreludeAuthError.passkeyNotConfigured { > // The app has no passkey configuration. > } catch PreludeAuthError.passkeyRegistrationFailed { > // The server rejected the new credential. > } > ``` > [tab] Android > > The system presents the ceremony, so pass an `Activity`: > > ```kotlin theme={null} > import so.prelude.android.auth.* > > val challenge = client.requestStepUp("prld:passkey:write") > client.sendStepUpOTP(challenge) > client.submitStepUpOTP(challenge, codeFromUser) > > try { > val registration = client.registerPasskey( > activity, > RegisterPasskeyOptions( > username = "user@example.com", // shown by the authenticator > displayName = "User", // optional, defaults to username > nickname = "Pixel", // optional, server-side label > ), > ) > if (registration.alreadyRegistered) { > // This authenticator was already registered for the user. > } > } catch (e: PreludeAuthError.Cancelled) { > // User dismissed the system sheet — not an error. > } catch (e: PreludeAuthError.InsufficientScope) { > // Session does not hold prld:passkey:write — run the step-up first. > } catch (e: PreludeAuthError.PasskeyNotSupported) { > // Device cannot run a passkey ceremony. > } catch (e: PreludeAuthError.PasskeyNotConfigured) { > // The app has no passkey configuration. > } catch (e: PreludeAuthError.PasskeyAlreadyRegistered) { > // The device already holds a passkey for this user. > } catch (e: PreludeAuthError.PasskeyRegistrationFailed) { > // The server rejected the new credential. > } > ``` > [tab] Flutter > > ```dart theme={null} > import 'package:prelude_flutter_auth_sdk/prelude_flutter_auth_sdk.dart'; > > final challenge = await client.requestStepUp(scope: 'prld:passkey:write'); > await client.sendStepUpOTP(challenge); > await client.submitStepUpOTP(challenge, codeFromUser); > > try { > final result = await client.registerPasskey( > RegisterPasskeyOptions( > username: 'user@example.com', // shown by the authenticator > displayName: 'User', // optional, defaults to username > nickname: 'iPhone', // optional, server-side label > ), > ); > if (result.alreadyRegistered) { > // This authenticator was already registered for the user. > } > } on CancelledException { > // User dismissed the system sheet — not an error. > } on InsufficientScopeException { > // Session does not hold prld:passkey:write — run the step-up first. > } on PasskeyNotSupportedException { > // Device cannot run a passkey ceremony. > } on PasskeyNotConfiguredException { > // The app has no passkey configuration. > } on PasskeyAlreadyRegisteredException { > // Android only: the device already holds a passkey for this user. > } on PasskeyRegistrationFailedException { > // The server rejected the new credential. > } > ``` > [tab] React Native > > ```ts theme={null} > import { > CancelledError, > InsufficientScopeError, > PasskeyAlreadyRegisteredError, > PasskeyNotConfiguredError, > PasskeyNotSupportedError, > PasskeyRegistrationFailedError, > } from "@prelude.so/react-native-auth-sdk"; > > const challenge = await client.requestStepUp("prld:passkey:write"); > await client.sendStepUpOTP(challenge); > await client.submitStepUpOTP(challenge, codeFromUser); > > try { > const result = await client.registerPasskey({ > username: "user@example.com", // shown by the authenticator > displayName: "User", // optional, defaults to username > nickname: "iPhone", // optional, server-side label > }); > if (result.alreadyRegistered) { > // This authenticator was already registered for the user. > } > } catch (e) { > if (e instanceof CancelledError) { > // User dismissed the system sheet — not an error. > } else if (e instanceof InsufficientScopeError) { > // Session does not hold prld:passkey:write — run the step-up first. > } else if (e instanceof PasskeyNotSupportedError) { > // Device cannot run a passkey ceremony. > } else if (e instanceof PasskeyNotConfiguredError) { > // The app has no passkey configuration. > } else if (e instanceof PasskeyAlreadyRegisteredError) { > // Android only: the device already holds a passkey for this user. > } else if (e instanceof PasskeyRegistrationFailedError) { > // The server rejected the new credential. > } else { > throw e; > } > } > ``` > > With the [React hooks](https://docs.prelude.so/auth/documentation/frontend-sdks/mobile/react-hooks.md), `useAuth()` exposes `registerPasskey`. | Field | Required | Description | | - | - | - | | `username` | Yes | Name shown by the authenticator. Typically the user's primary email or phone number. | | `displayName` | No | Display name shown next to the name. Falls back to `username`. | | `nickname` | No | Server-side label for your "Manage your passkeys" screen ("iPhone", "Work phone"). | A user can register several passkeys. Each registration consumes the `prld:passkey:write` scope: run a new step-up before the next registration, and before you list, rename, or delete passkeys. When the device already holds a passkey for this user, a new registration on Android (also through Flutter and React Native) throws the "passkey already registered" error (see [Errors](#errors)). `alreadyRegistered` is `true` only when the authenticator returns a credential that Prelude already stores. ## Sign in with a passkey `loginWithPasskey` signs a user in with the platform authenticator. The app sends no identifier: the authenticator offers the passkeys it holds for the relying party, and the server resolves the user from the one the user picks. On success the SDK persists the session tokens in the platform's secure store. Requires `login_enabled` in the passkey configuration. > [tab] iOS > > ```swift theme={null} > import PreludeAuth > > do { > let user = try await client.loginWithPasskey() > // User is now authenticated. > } catch PreludeAuthError.cancelled { > // User dismissed the system sheet — not an error. > } catch PreludeAuthError.passkeyNotSupported { > // Device cannot run a passkey ceremony. > } catch PreludeAuthError.passkeyNotConfigured { > // Passkey login is not enabled for the app. > } catch PreludeAuthError.unauthorized { > // No matching passkey, or the assertion failed verification. > } catch PreludeAuthError.rateLimited { > // Too many attempts. > } > ``` > [tab] Android > > ```kotlin theme={null} > import so.prelude.android.auth.* > > try { > val user = client.loginWithPasskey(activity) > // User is now authenticated. > } catch (e: PreludeAuthError.Cancelled) { > // User dismissed the system sheet — not an error. > } catch (e: PreludeAuthError.PasskeyNotSupported) { > // Device cannot run a passkey ceremony. > } catch (e: PreludeAuthError.PasskeyNotConfigured) { > // Passkey login is not enabled for the app. > } catch (e: PreludeAuthError.PasskeyStepUnavailable) { > // The device holds no usable passkey for this app. > } catch (e: PreludeAuthError.Unauthorized) { > // No matching passkey, or the assertion failed verification. > } catch (e: PreludeAuthError.RateLimited) { > // Too many attempts. > } > ``` > [tab] Flutter > > ```dart theme={null} > import 'package:prelude_flutter_auth_sdk/prelude_flutter_auth_sdk.dart'; > > try { > final user = await client.loginWithPasskey(); > // User is now authenticated. > } on CancelledException { > // User dismissed the system sheet — not an error. > } on PasskeyNotSupportedException { > // Device cannot run a passkey ceremony. > } on PasskeyNotConfiguredException { > // Passkey login is not enabled for the app. > } on PasskeyStepUnavailableException { > // The device holds no usable passkey for this app. > } on UnauthorizedException { > // No matching passkey, or the assertion failed verification. > } on RateLimitedException { > // Too many attempts. > } > ``` > [tab] React Native > > ```ts theme={null} > import { > CancelledError, > PasskeyNotConfiguredError, > PasskeyNotSupportedError, > PasskeyStepUnavailableError, > RateLimitedError, > UnauthorizedError, > } from "@prelude.so/react-native-auth-sdk"; > > try { > const user = await client.loginWithPasskey(); > // User is now authenticated. > } catch (e) { > if (e instanceof CancelledError) { > // User dismissed the system sheet — not an error. > } else if (e instanceof PasskeyNotSupportedError) { > // Device cannot run a passkey ceremony. > } else if (e instanceof PasskeyNotConfiguredError) { > // Passkey login is not enabled for the app. > } else if (e instanceof PasskeyStepUnavailableError) { > // The device holds no usable passkey for this app. > } else if (e instanceof UnauthorizedError) { > // No matching passkey, or the assertion failed verification. > } else if (e instanceof RateLimitedError) { > // Too many attempts. > } else { > throw e; > } > } > ``` > > With the [React hooks](https://docs.prelude.so/auth/documentation/frontend-sdks/mobile/react-hooks.md), `useSignIn()` exposes `loginWithPasskey`. A dismissed sheet resolves without setting `error`. The server returns the same "unauthorized" error for an unknown user and for a bad signature, so an attacker cannot use it to find valid users. ### AutoFill (iOS) On iOS, the `autofill` option offers matching passkeys in the keyboard's AutoFill row instead of a modal sheet, when the user focuses a username field. The request shows no sheet and stays active, so start it when your sign-in screen appears. Android always shows the Credential Manager sheet. > [tab] iOS > > ```swift theme={null} > let user = try await client.loginWithPasskey(.init(autofill: true)) > ``` > [tab] Android > > Not available: `loginWithPasskey` always presents the Credential Manager sheet. > [tab] Flutter > > ```dart theme={null} > final user = await client.loginWithPasskey( > const PasskeyLoginOptions(autofill: true), > ); > ``` > > The option has no effect on Android. > [tab] React Native > > ```ts theme={null} > const user = await client.loginWithPasskey({ autofill: true }); > ``` > > The option has no effect on Android. ## Use a passkey in a step-up When a [step-up](https://docs.prelude.so/auth/documentation/frontend-sdks/mobile/step-up.md) challenge has `verify_passkey` as its current step, advance it with the platform authenticator instead of a code. `continueStepUpWithPasskey` has the same contract as `submitStepUpOTP`: it returns the next challenge, or nothing when the step-up is complete. > [tab] iOS > > ```swift theme={null} > let challenge = try await client.requestStepUp(scope: "transfer:write") > > if challenge.currentStep == "verify_passkey" { > do { > let next = try await client.continueStepUpWithPasskey(challenge) > // `next` is nil when the step-up is complete. > } catch PreludeAuthError.cancelled { > // Dismissed — the challenge is still usable for a fallback step. > } catch PreludeAuthError.passkeyStepUnavailable { > // No registered passkey, or the assertion failed. Use a fallback. > } > } > ``` > [tab] Android > > ```kotlin theme={null} > val challenge = client.requestStepUp("transfer:write") > > if (challenge.currentStep == "verify_passkey") { > try { > val next = client.continueStepUpWithPasskey(activity, challenge) > // `next` is null when the step-up is complete. > } catch (e: PreludeAuthError.Cancelled) { > // Dismissed — the challenge is still usable for a fallback step. > } catch (e: PreludeAuthError.PasskeyStepUnavailable) { > // No registered passkey, or the assertion failed. Use a fallback. > } > } > ``` > [tab] Flutter > > ```dart theme={null} > final challenge = await client.requestStepUp(scope: 'transfer:write'); > > if (challenge.currentStep == 'verify_passkey') { > try { > final next = await client.continueStepUpWithPasskey(challenge); > // `next` is null when the step-up is complete. > } on CancelledException { > // Dismissed — the challenge is still usable for a fallback step. > } on PasskeyStepUnavailableException { > // No registered passkey, or the assertion failed. Use a fallback. > } > } > ``` > [tab] React Native > > ```ts theme={null} > import { > CancelledError, > PasskeyStepUnavailableError, > } from "@prelude.so/react-native-auth-sdk"; > > const challenge = await client.requestStepUp("transfer:write"); > > if (challenge.currentStep === "verify_passkey") { > try { > const next = await client.continueStepUpWithPasskey(challenge); > // `next` is null when the step-up is complete. > } catch (e) { > if (e instanceof CancelledError) { > // Dismissed — the challenge is still usable for a fallback step. > } else if (e instanceof PasskeyStepUnavailableError) { > // No registered passkey, or the assertion failed. Use a fallback. > } else { > throw e; > } > } > } > ``` > > With the [React hooks](https://docs.prelude.so/auth/documentation/frontend-sdks/mobile/react-hooks.md), `useStepUp()` exposes `continueStepUpWithPasskey`. To let users without a passkey complete the step-up, configure a fallback step: see [Fall back to OTP for users without a passkey](https://docs.prelude.so/auth/documentation/passkey.md#fall-back-to-otp-for-users-without-a-passkey). ## Manage registered passkeys Build a "Manage your passkeys" screen with three methods. All three require `prld:passkey:write`, the same scope as registration, so run the step-up before you open the screen. A registration consumes the scope, so run the step-up again after the user adds a passkey from this screen. Listing returns an empty list when the user has no passkey. Pass an empty nickname to clear the label. > [tab] iOS > > ```swift theme={null} > let passkeys = try await client.listPasskeys() > > try await client.renamePasskey(passkeys[0].credentialID, nickname: "My iPhone") > try await client.deletePasskey(passkeys[0].credentialID) > ``` > [tab] Android > > ```kotlin theme={null} > val passkeys = client.listPasskeys() > > client.renamePasskey(passkeys.first().credentialId, "My Pixel") > client.deletePasskey(passkeys.first().credentialId) > ``` > [tab] Flutter > > ```dart theme={null} > final passkeys = await client.listPasskeys(); > > await client.renamePasskey(passkeys.first.credentialID, 'Work phone'); > await client.deletePasskey(passkeys.first.credentialID); > ``` > [tab] React Native > > ```ts theme={null} > const passkeys = await client.listPasskeys(); > > await client.renamePasskey(passkeys[0].credentialID, "Work phone"); > await client.deletePasskey(passkeys[0].credentialID); > ``` Each credential carries its identifier, the optional `nickname`, the `transports` reported by the authenticator, the `backupState` (whether the passkey is synced), and the creation and last-use times. ## Errors | Error | Triggered by | Typical recovery | | - | - | - | | Cancelled | The user dismissed the system sheet | None. Leave the screen as it is | | Passkey not supported | The device or OS version cannot run a passkey ceremony | Offer another sign-in method | | Passkey not configured | The app has no passkey configuration, or `login_enabled` is off for `loginWithPasskey` | Set the passkey configuration | | Insufficient scope | The session does not hold `prld:passkey:write` | Run the step-up, then retry | | Passkey registration failed | The server rejected the new credential | Retry, or use another authenticator | | Passkey already registered | Android only: the device already holds a passkey for this user | Treat it as registered | | Passkey step unavailable | The device holds no usable passkey (login or step-up), or the assertion failed during a step-up | Offer another sign-in method, or use a fallback step | | Conflict | Another passkey ceremony is already in progress | Wait for the first call to finish | | Unauthorized | No matching passkey, or the assertion failed during login | Offer another sign-in method | Each SDK names these errors in its own convention, for example `PreludeAuthError.passkeyNotSupported` (iOS), `PreludeAuthError.PasskeyNotSupported` (Android), `PasskeyNotSupportedException` (Flutter), and `PasskeyNotSupportedError` (React Native). If a ceremony fails although the code is correct, check the [platform setup](#platform-setup) first: a missing association on either side makes the operating system refuse the ceremony before it reaches Prelude. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.