Passkey

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 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 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). 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: <APP_ID>.session.prelude.dev, or your custom domain. 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.

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 `<TeamID>.<bundleID>`.
`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).

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 for all fields.

Only ios_app_ids, android_apps, login_enabled, aaguid_allowlist, and aaguid_blocklist keep their stored value when you omit them.

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

iOS
Android
Flutter
React Native

Add the Associated Domains capability to your app target, with one entry for the relying-party host:

webcredentials:auth.example.com

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:

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 <application> in AndroidManifest.xml:

<meta-data
    android:name="asset_statements"
    android:resource="@string/asset_statements" />

<!-- res/values/strings.xml -->
<string name="asset_statements" translatable="false">
    [{\"include\":\"https://auth.example.com/.well-known/assetlinks.json\"}]
</string>

With only the server side in place, registration and login fail with RP ID cannot be validated.

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):

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 <application> in android/app/src/main/AndroidManifest.xml:

<meta-data
    android:name="asset_statements"
    android:resource="@string/asset_statements" />

<!-- android/app/src/main/res/values/strings.xml -->
<string name="asset_statements" translatable="false">
    [{\"include\":\"https://auth.example.com/.well-known/assetlinks.json\"}]
</string>

On Android, passkey calls need a foreground Activity. A call made while the Flutter engine is attached to no Activity throws InvalidConfigurationException.

Add the relying-party host to the config plugin in expo.plugins:

["@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.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 grants. Complete the step-up first, then register.

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.

iOS
Android
Flutter
React Native

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.
}

The system presents the ceremony, so pass an Activity:

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.
}

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.
}

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, 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). alreadyRegistered is true only when the authenticator returns a credential that Prelude already stores. 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.

iOS
Android
Flutter
React Native

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.
}

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.
}

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.
}

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, 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.

iOS
Android
Flutter
React Native

let user = try await client.loginWithPasskey(.init(autofill: true))

Not available: loginWithPasskey always presents the Credential Manager sheet.

final user = await client.loginWithPasskey(
  const PasskeyLoginOptions(autofill: true),
);

The option has no effect on Android.

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 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.

iOS
Android
Flutter
React Native

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.
    }
}

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.
    }
}

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.
  }
}

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, 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.

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.

iOS
Android
Flutter
React Native

let passkeys = try await client.listPasskeys()

try await client.renamePasskey(passkeys[0].credentialID, nickname: "My iPhone")
try await client.deletePasskey(passkeys[0].credentialID)

val passkeys = client.listPasskeys()

client.renamePasskey(passkeys.first().credentialId, "My Pixel")
client.deletePasskey(passkeys.first().credentialId)

final passkeys = await client.listPasskeys();

await client.renamePasskey(passkeys.first.credentialID, 'Work phone');
await client.deletePasskey(passkeys.first.credentialID);

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 first: a missing association on either side makes the operating system refuse the ceremony before it reaches Prelude.

Documentation

API Reference

Requirements

Platform setup

Authorize your apps in the passkey configuration

Declare the relying-party host in your app

Register a passkey

AutoFill (iOS)

Use a passkey in a step-up

Manage registered passkeys

Errors

​Requirements

​Platform setup

​Authorize your apps in the passkey configuration

​Declare the relying-party host in your app

​Register a passkey

​Sign in with a passkey

​AutoFill (iOS)

​Use a passkey in a step-up

​Manage registered passkeys

​Errors

Requirements

Platform setup

Authorize your apps in the passkey configuration

Declare the relying-party host in your app

Register a passkey

Sign in with a passkey

AutoFill (iOS)

Use a passkey in a step-up

Manage registered passkeys

Errors