Skip to main content

Passkey Management

Passkeys provide secure, passwordless authentication for your users. Volr SDK uses passkeys to secure user wallets, providing a better user experience than seed phrases.

What are Passkeys?​

Passkeys are cryptographic credentials that use WebAuthn/FIDO2 standards. They provide:

  • Security: Private keys never leave the device
  • Convenience: No passwords or seed phrases to remember
  • Cross-device: Can be synced across devices via iCloud Keychain or Google Password Manager

Passkey Enrollment Flow​

When a user first authenticates (via SigninModal or BYO Auth), they must enroll a passkey to secure their wallet:

[User authenticates]
    ↓
[Check if passkey exists]
    ↓
[No passkey] → Show PasskeyEnrollView
    ↓
[User creates passkey]
    ↓
[Passkey enrolled]
    ↓
[Wallet ready]

Automatic Enrollment​

The SigninModal component automatically handles passkey enrollment:

import { SigninModal } from '@volr/react-ui';

function App() {
  const [showSignin, setShowSignin] = useState(false);

  return (
    <SigninModal
      isOpen={showSignin}
      onClose={() => setShowSignin(false)}
      // Passkey enrollment happens automatically after login
    />
  );
}

Manual Enrollment​

If you're using BYO Auth, you can manually trigger passkey enrollment:

import { PasskeyEnrollView } from '@volr/react-ui';
import { useVolr } from '@volr/react';

function App() {
  const { user } = useVolr();
  const [showEnroll, setShowEnroll] = useState(false);

  // Check if user needs passkey enrollment
  const needsPasskey = user && !user.keyStorageType;

  if (needsPasskey && showEnroll) {
    return (
      <PasskeyEnrollView
        wrapInModal={false}
        onComplete={() => {
          console.log('Passkey enrolled!');
          setShowEnroll(false);
        }}
        onError={(error) => {
          console.error('Passkey enrollment failed:', error);
        }}
      />
    );
  }

  return (
    <button onClick={() => setShowEnroll(true)}>
      Set Up Passkey
    </button>
  );
}

PasskeyEnrollView Component​

Props​

PropTypeRequiredDescription
wrapInModalbooleanNoWrap in modal (default: true)
onComplete() => voidYesCalled when enrollment succeeds
onError(error: Error) => voidNoCalled when enrollment fails
onClose() => voidNoCalled when user cancels (only if wrapped in modal)

Usage​

import { PasskeyEnrollView } from '@volr/react-ui';

function EnrollPasskey() {
  return (
    <PasskeyEnrollView
      wrapInModal={true}
      onComplete={() => {
        console.log('Passkey enrolled successfully!');
      }}
      onError={(error) => {
        console.error('Enrollment error:', error);
      }}
      onClose={() => {
        console.log('User cancelled enrollment');
      }}
    />
  );
}

Checking Passkey Status​

Check if a user has a passkey enrolled:

import { useVolr } from '@volr/react';

function UserStatus() {
  const { user } = useVolr();

  if (!user) {
    return <div>Not logged in</div>;
  }

  if (user.keyStorageType === 'passkey') {
    return <div>Passkey is set up ✓</div>;
  }

  return <div>Passkey not set up. Please enroll.</div>;
}

Passkey Recovery​

If a user loses access to their device, they can recover their account:

  1. Account Recovery: User authenticates with their original method (email, social, etc.)
  2. New Passkey: User enrolls a new passkey on their new device
  3. Wallet Access: User regains access to their wallet

The wallet is tied to the user account, not the specific passkey device.

Best Practices​

1. Prompt Early​

Prompt users to enroll a passkey immediately after authentication:

import { useVolr } from '@volr/react';
import { useEffect } from 'react';

function App() {
  const { user } = useVolr();
  const [showEnroll, setShowEnroll] = useState(false);

  useEffect(() => {
    // Prompt if user is logged in but doesn't have passkey
    if (user && !user.keyStorageType) {
      setShowEnroll(true);
    }
  }, [user]);

  // ... render PasskeyEnrollView
}

2. Explain Benefits​

Help users understand why they should enroll a passkey:

function PasskeyPrompt() {
  return (
    <div>
      <h2>Secure Your Wallet</h2>
      <p>
        Set up a passkey to secure your wallet. Passkeys are more secure
        than passwords and easier to use.
      </p>
      <PasskeyEnrollView onComplete={() => {}} />
    </div>
  );
}

3. Handle Errors Gracefully​

Some devices or browsers may not support passkeys:

<PasskeyEnrollView
  onError={(error) => {
    if (error.message.includes('not supported')) {
      // Show fallback message
      alert('Your device does not support passkeys. Please use a different device.');
    } else {
      // Handle other errors
      console.error('Passkey enrollment failed:', error);
    }
  }}
/>

Troubleshooting​

Passkey Not Supported​

If the user's device doesn't support passkeys, you can:

  1. Check support before showing enrollment:
const isPasskeySupported = 
  window.PublicKeyCredential !== undefined &&
  typeof window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable === 'function';

if (!isPasskeySupported) {
  // Show alternative message
}
  1. Provide alternative authentication methods

Enrollment Fails​

Common reasons for enrollment failure:

  • User cancels: User closes the browser dialog
  • Device not supported: Device doesn't support WebAuthn
  • Network error: Connection issues during enrollment

Handle these cases appropriately in your onError callback.

Next Steps​