Passkeys
Passkeys are account credentials. The host may unlock the credential with fingerprint, face, device PIN, password manager, phone, or hardware key, but the app receives WebAuthn registration or authentication data that the server must verify.
By the end of this guide, you will know how to build a sign-in button that receives a server challenge, asks the host for a credential assertion, and sends that assertion back to the server. The same pattern applies to larger apps: declare the capability when native configuration is needed, store the result in typed app state, request the host operation from a reducer, and test both success and failure with a memory host.
Do not use passkeys for local-only unlock when no server identity is involved. Use biometrics for local verification and passkeys for account registration or sign-in.
1. Start with the state the screen needs
Add the smallest state fields the screen needs to render honestly. For this flow, useful state is:
#[derive(Default)]
struct PasskeyState {
// Add these fields to your existing app state.
login_challenge: Vec<u8>,
known_credentials: Vec<PasskeyCredentialDescriptor>,
pending_assertion: Option<PasskeyAuthenticationResult>,
login_error: Option<String>,
}
impl GlobalState for PasskeyState {}
State is the source of truth for the UI. Do not store whether the host "probably" succeeded; wait for the typed success action and store the returned value.
2. Configure the target and host
Run this once from the project root:
fission add-capability passkeys --project-dir .
That command records the capability in fission.toml and updates generated platform files where Fission can do so safely. It does not replace product-specific review of native manifests, usage text, entitlements, service identifiers, domains, or store policy.
The CLI records the capability, but domain association is product-specific. Web needs a secure origin and relying-party id. iOS and macOS usually need associated domains such as webcredentials:example.com. Android usually needs Digital Asset Links. Fission cannot invent those because they must match the production domain and app identifiers.
This is the difference between the Fission API, a provider, and packaging configuration:
•
The Fission API is the typed Rust contract your reducer calls, such as ctx.effects.camera().capture_photo(...).
•
The provider is the shell-side Rust implementation that turns that typed request into the correct OS, browser, or hardware call.
•
Packaging configuration is the manifest, plist, entitlement, service-worker, protocol, domain, or store metadata that lets the platform permit that call in a real installed app.
If the API exists but the provider is missing, the request returns a typed unsupported error. If the provider exists but packaging is missing, the operating system or browser may deny the request before the provider can complete it.
3. Define reducers for success and failure
Capability work finishes later, after the reducer that started it has returned. You therefore need one reducer for the successful result and one reducer for the error path.
#[fission_reducer(PasskeyAssertionReady)]
fn on_passkey_assertion_ready(state: &mut PasskeyState, assertion: PasskeyAuthenticationResult) {
state.pending_assertion = Some(assertion);
state.login_error = None;
}
#[fission_reducer(PasskeySignInFailed)]
fn on_passkey_sign_in_failed(state: &mut PasskeyState, error: PasskeyError) {
state.pending_assertion = None;
state.login_error = Some(error.message);
}
Keep both paths explicit. A denied permission, unavailable device, unsupported host, or cancelled prompt is not an exceptional mystery; it is normal product behavior the UI should explain.
4. Request the capability from a reducer
Call the capability from the reducer that handles the user's intent. The reducer queues a host effect and returns. The runtime later dispatches either the success reducer or the failure reducer.
ctx.effects
.passkeys()
.authenticate(PasskeyAuthenticationRequest {
relying_party_id: "example.com".into(),
challenge: state.login_challenge.clone(),
allow_credentials: state.known_credentials.clone(),
user_verification: PasskeyUserVerification::Preferred,
mediation: PasskeyMediation::Conditional,
timeout_ms: Some(60_000),
})
.on_ok(ctx.effects.bind(
PasskeyAssertionReady(PasskeyAuthenticationResult::default()),
reduce_with!(on_passkey_assertion_ready),
))
.on_err(ctx.effects.bind(
PasskeySignInFailed(PasskeyError::default()),
reduce_with!(on_passkey_sign_in_failed),
));
The call does not run the OS API directly. It records a typed host request. That keeps shared app logic portable across Fission targets where the capability applies, plus static-site previews and tests.
5. Trigger the reducer from the UI
Wire the user-facing control with the normal Fission action pattern. This example uses a small widget so the binding has one clear home.
struct PasskeySignInButton;
impl From<PasskeySignInButton> for Widget {
fn from(component: PasskeySignInButton) -> Self {
let (ctx, view) = fission::build::current::<PasskeyState>();
let run = with_reducer!(ctx, SignInWithPasskey, on_sign_in_with_passkey);
Button::new("Sign in with passkey")
.disabled(false)
.on_press(run)
.into()
}
}
Rename the widget and action for your product, but keep the shape: the widget dispatches one typed action, the reducer starts the capability request, and the success or failure reducer updates state.
6. Provide and test the host behavior
Register a PasskeyHost with .with_passkey_host(...). Use MemoryPasskeyHost for reducer tests. A real provider only gathers credential data; the relying-party server must verify registration and authentication results before the app treats the user as signed in.
Use fixed challenges and memory results for reducer tests. Integration tests should cover server rejection, cancellation, unsupported host, and mismatched relying-party id.
A useful first test creates the app with the memory host, dispatches the start action, feeds the queued effect through the host, and asserts that the reducer updates state from the returned payload. Add a second test for the error path before you ship the screen.
Platform expectations
Web, Android, iOS, macOS, and Windows all have passkey routes. Linux support depends on browser, desktop credential providers, and hardware authenticators. Secure origin and domain ownership are non-negotiable for production.
For a cross-platform summary, read the capability matrix. For exact request fields, provider traits, and generated configuration, see the Passkeys reference.
Finished capability flow
A complete Passkeys integration has all of these pieces in place:
Piece | What should exist |
|---|---|
Configuration | fission.toml declares the capability and generated platform files contain the permission text, manifest entry, entitlement, domain, or protocol metadata the target needs. |
State | App state records the in-flight flag, the successful value, and the user-facing error separately. |
Reducers | One reducer starts the host request, one handles success, and one handles denial, unsupported hosts, cancellation, or provider errors. |
Provider | The shell registers a real provider for production and a memory provider for tests. |
Tests | At least one test covers success and one covers permission denial or unsupported host behavior. |
Diagnose capability failures
Capability failures should be safe to retry and easy to explain. Start by checking fission.toml, then run fission doctor, then inspect the generated target files. If the provider is missing, the request should return an unsupported error. If the provider exists but the platform configuration is wrong, the OS or browser will usually deny the request before the provider can complete it. Keep those cases distinct in the UI so users know whether they can retry, change settings, connect hardware, or choose another path.
Fission
A cross-platform, GPU-accelerated user interface framework for Rust. MIT licensed.
Copyright (c) 2026 Fission
Ready to use today. Widget APIs are expected to remain stable; some runtime and shell APIs may change before 1.0.0.
Fission 0.7.0