PassKi

How it works

People keep signing in the way they do today. Once signed in, they add a passkey: the device keeps a private key and your server a public one. Next time, one tap signs them in. For each passkey step, your server creates the options and verifies the result; PassKi shows the device's sheet in between, from commonMain:

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

// 2. Signed in, in Settings: add a passkey
passkeys.register(api.registrationOptions())
    .onSuccess { api.finishRegistration(it.json) } // your server stores the new passkey

// 3. Next time, on the sign-in screen
passkeys.signIn(api.authenticationOptions())
    .onSuccess { api.finishSignIn(it.json) }       // your server verifies it: the user is signed in

The whole flow, with Settings, deleting and renaming: Passkeys as an extra sign-in.

• Does: shows the platform's own sheet (Credential Manager on Android, AuthenticationServices on iOS, navigator.credentials in the browser) and returns a typed PasskeyResult with the response JSON, unchanged.
• Doesn't: verify responses, store credentials, or talk to your server. Verifying is your server's job, with any WebAuthn library (how). More: Concepts, Security model.
• Tests without a device: FakePasskeys signs real responses that webauthn4j and java-webauthn-server verify, so your app's and your server's tests run on the JVM (Testing).

Every failure is a PasskeyError with a category you can when over. A setup mistake says what to fix, and PassKi logs it, so even a release build tells you:

E PassKi  : signIn failed: Misconfigured [AND-03]: … Fix: add the SHA-256 fingerprint … Docs: …/checks/AND-03

When error.isUserCancellation is true, the user closed the sheet: show nothing. What to show users · Troubleshooting · Logging

Setup: your app, your domain and your server trust each other

The device only offers a passkey for example.com if example.com lists your app (a web page there needs no files), and your server only accepts origins it knows. Your domain is the RP ID: it can't change.

With the plugin, in your Android app module:

plugins { id("com.alirezaiyan.passki") version "0.1.0-alpha05" }
passki { rpId = "example.com" }

./gradlew passkiSetup writes both well-known files and the iOS entitlement, and prints your server's allowed origins. Upload the files to https://example.com/.well-known/, then ./gradlew passkiCheck checks the live domain, your Xcode project and, if configured, your server's origins (also in CI). Setup tooling

By hand: serve /.well-known/assetlinks.json and /.well-known/apple-app-site-association, add webcredentials:example.com to the iOS entitlements, and allow https://example.com plus one android:apk-key-hash: origin per signing key on your server. Checklist

Either way, PasskeyDoctor.run("example.com") in a debug build checks the domain and the device, and prints fixes.

Get started

commonMain.dependencies {
    implementation(project.dependencies.platform("com.alirezaiyan.passki:passki-bom:0.1.0-alpha05"))
    implementation("com.alirezaiyan.passki:passki") // the BOM keeps every PassKi library on one version
}
commonTest.dependencies { implementation("com.alirezaiyan.passki:passki-test") }

Android needs Kotlin 2.1+ and runs passkeys on Android 9+; iOS 16+ and the web need Kotlin 2.2+ (requirements). Then follow the Quickstart to a first verified passkey with your own server, or try it against the hosted demo server, with nothing to set up.

More: Guides · Usage · Platforms · Troubleshooting · Security model · All docs · API reference · CHANGELOG · Versioning

License

Apache-2.0 © Ali Rezaiyan. Contributions welcome: see CONTRIBUTING.md.