Passkeys (2FA)

Right after signup, walk the user through creating a passkey. It is a second factor for their wallet: it does not replace the silent device key and it never signs transactions. What it does is let them log in on a new device without having to find one that's already logged in.

Treat it as two-factor authentication in your UI. Show the prompt immediately after the wallet is ready, framed as "Turn on device approvals so you never get locked out" — not as a signing step. That framing is what keeps the UX coherent: the user already authenticated and got a wallet, and this is the safety net on top.

Why a passkey

Without a passkey, adding a new device requires either an already-registered device (the multi-device approval flow) or the recovery passphrase (recovery). Both can fail the user at the worst moment: the other device isn't nearby, or the code was lost.

A passkey removes that dependency. Because it syncs across the user's devices through the OS, a single WebAuthn prompt from any browser can authorize the new device's key on-chain — no second device hunt, no passphrase. It is the lowest-friction path to "log in on my new phone."

Control when it's asked (React SDK)

If you use the CavosProvider with the built-in auth modal, the kit shows a "Secure your account" step automatically right after a brand-new wallet is created. You decide — per app — whether that step interrupts onboarding, runs as an optional nudge, or is skipped entirely. The secureStep modal option is the single knob for this:

import { CavosProvider } from '@cavos/kit/react';

<CavosProvider
  config={config}
  modal={{
    appName: 'My App',
    // When the passkey / recovery prompt appears after signup:
    secureStep: 'optional', // 'optional' | 'required' | 'off'
  }}
>
  {children}
</CavosProvider>

Picking the right moment

The right value depends on where in the user journey asking for a passkey feels natural, not disruptive:

• 'off' — ask later. Friction-free onboarding. Drop the user straight into the app, then surface the passkey prompt from your own UI once they've hit an "aha" moment (first transaction, settings page, or a dedicated security screen). You can still enroll any time with enrollPasskey from useCavos() — secureStep: 'off' only removes the automatic post-signup screen.
• 'optional' — ask now, let them skip. The default. Good when you want to plant the seed early but respect the user's pace; the skip keeps conversion high while the prompt keeps the option visible.
• 'required' — ask now, no skipping. Best for custody-like UX, treasuries, or any context where losing device access is unacceptable. Pair it with the recovery passphrase fallback (the screen offers both) so the user always has a path forward even without a platform authenticator.

Set it up after signup

Once connect returns status: "ready", gate on platform support and enroll. enrollPasskey does two things in one call: it creates the credential (a system prompt the user confirms with biometrics / screen lock) and registers its public key on-chain as an approver via addApprover. It is gasless, device-signed, and idempotent.

import { Cavos, PasskeySigner } from "@cavos/kit";

// cavos is ready (status === "ready") right after signup.
if (await PasskeySigner.isSupported()) {
  const passkey = new PasskeySigner();               // rpId defaults to your hostname
  const { publicKey } = await cavos.enrollPasskey(passkey, {
    userId: identity.userId,
    userName: identity.email ?? identity.userId,
  });
  // publicKey { x, y } is now a registered approver of this wallet.
}

Only the passkey's public key is registered on-chain. The credential itself is held and synced by the OS authenticator — the kit never stores it.

Approve a new device with a passkey

When the same identity connects on a fresh browser, it lands on the same wallet address but with status: "needs-device-approval" — this device's key isn't an authorized signer yet. If the user enrolled a passkey, they can self-approve from that new browser in one prompt:

const cavos = await Cavos.connect({ /* ...same identity + appSalt... */ });

if (cavos.status === "needs-device-approval") {
  const passkey = new PasskeySigner();
  // One prompt: the synced passkey authorizes adding THIS device's key.
  await cavos.approveThisDeviceWithPasskey({ passkey });
  // cavos is now ready; no second device required.
}

Internally, the kit builds a per-chain "leaf" from the new device key and the on-chain passkey nonce, the passkey signs a challenge over it, and an add_signer_via_passkey call is submitted. The assertion does not carry the public key, so the kit recovers both secp256r1 candidates and matches the enrolled approver via an on-chain view — no backend lookup.

Prerequisites & limits

• Secure context required. WebAuthn needs HTTPS or http://localhost. A LAN IP fails — the kit throws an actionable error pointing you to localhost, a real HTTPS domain, or a tunnel (cloudflared / ngrok). The silent device key works over an IP; passkeys don't.
• Check support first. Gate enrollment on await PasskeySigner.isSupported() (it checks for a platform authenticator). On unsupported platforms, fall back to the multi-device and recovery flows.
• RP ID. Defaults to window.location.hostname. Pass rpId explicitly only if you need a different registrable domain.
• Starknet mainnet caveat. Passkey approval currently works on Sepolia only. The mainnet account class hasn't been re-declared with the add_signer_via_passkey surface yet, so on Starknet mainnet use multi-device / recovery instead. Solana and Stellar route passkey approval through their relayers and are not affected.

Non-custodial

A passkey strengthens the wallet without introducing custody:

• Only the passkey's public key is on-chain. The credential stays with the OS authenticator; Cavos never receives it.
• add_signer_via_passkey is a public external that is authorized solely by the embedded WebAuthn assertion — it still requires a valid signature. Cavos sponsors the gas but cannot add a signer without the passkey's assertion.
• Removing the passkey is an on-chain remove_approver, gated to the account like any signer change.

Combine it with the other two fallbacks for the strongest setup:

1. Passkey (this page) — self-serve approval on any new device.
2. Multiple devices (multi-device) — approve from an existing, logged-in device.
3. Passphrase backup (recovery) — the last resort when all devices and the passkey are gone.

See Concepts → non-custodial model for the full security rationale.