A fingerprint unlock takes about a second. In that second your app hands off a request, a piece of secure hardware makes a decision you are not allowed to observe, and you get back a single verdict. Most apps treat that verdict as the end of the story. Production incidents show it is the beginning of one.

This post walks through what the platform does, how to wire BiometricPrompt in idiomatic Kotlin, and the failure modes that tend to surface only after release. The running example is a fictional notes app, Lockbox , that keeps its database passphrase wrapped by a hardware-backed key.

1. The mental model: you ask, the platform answers

You never touch a fingerprint. You describe what you need, the system shows its own UI, and you receive an outcome.

Two consequences follow from this design:

Your process cannot see biometric data. There is no API that returns an image, a template, or a match score, and no flag that turns one on.

Your process cannot draw the prompt.…