Passkeys

interface Passkeys

Entry point. Obtain with Passkeys; no platform handles needed.

Every optionsJson parameter is the WebAuthn options JSON produced by your server, optionally wrapped in {"publicKey": ...}. It must name the RP ID (rp.id in creation options, rpId in request options) as a bare domain such as example.com: browsers derive it from the page's origin, but apps have no origin, so a missing or malformed RP ID fails with PasskeyError.InvalidOptions. Every returned json is ready to POST to your server's verifier.

Threads and cancellation.

  • Every call is main-safe: call it from any dispatcher, including Dispatchers.Main. PassKi moves UI work to the main thread itself and never blocks the calling thread; the result comes back in the calling coroutine.

  • Cancelling the calling coroutine (e.g. the screen's scope) withdraws the request: PassKi asks the platform to close the sheet (Android credential providers may keep theirs open), the call ends with CancellationException, and a passkey picked afterwards is discarded. That's different from PasskeyError.Cancelled, which means the user closed the sheet.

  • One sheet at a time: register, signIn (except SignInMode.Autofill), signInOrPassword and upgrade fail at once with PasskeyError.Interrupted while another of these calls is still pending, for example after a double tap. Autofill sign-in waits for the pending call to finish instead.

Implementing this interface is supported (e.g. for fakes; prefer passki-test's FakePasskeys). New members will only ever be added with default implementations, so implementations stay source- and binary-compatible.

Samples

val passkeys = Passkeys() // no Activity, no UIWindow

passkeys.register(server.registrationOptions())
    .onSuccess { server.finishRegistration(it.json) } // your server verifies the response
    .onFailure { error ->
        when (error.category) {
            PasskeyErrorCategory.UserCancelled -> Unit // the user closed the sheet
            PasskeyErrorCategory.Setup -> showError("Passkeys aren't working right now.") // PassKi logs the fix
            else -> showError(error.message)
        }
    }

passkeys.signIn(server.authenticationOptions(), SignInMode.ImmediateOnly)
    .onSuccess { server.finishSignIn(it.json) }

Properties

Link copied to clipboard
abstract val signals: PasskeySignals

Keeps credential providers in sync with the server (WebAuthn Signal API).

Functions

Link copied to clipboard
suspend fun Passkeys.autofillSignIn(optionsJson: String, anchor: View): PasskeyResult<PasskeyAssertion>

signIn(optionsJson, SignInMode.Autofill) with the request attached to the focused view inside anchor (or anchor itself), instead of the focused view PassKi finds on its own.

Link copied to clipboard
abstract suspend fun capabilities(): PasskeyCapabilities

What this device/OS supports, so UI can adapt before showing passkey buttons.

Link copied to clipboard
Link copied to clipboard
abstract suspend fun signInOrPassword(optionsJson: String): PasskeyResult<SignInCredential>
Link copied to clipboard
abstract suspend fun upgrade(optionsJson: String): PasskeyResult<PasskeyRegistration>

Silently creates a passkey for a user who just signed in with a password (conditional create). The provider decides whether to create one; no sheet is shown. Requires PasskeyCapabilities.conditionalCreate. Typical errors: PasskeyError.NotSupported, PasskeyError.AlreadyRegistered, PasskeyError.InvalidOptions, PasskeyError.Misconfigured.