Testing on Mobile Devices

WebAuthn requires HTTPS. During development, you need a way to expose your local server over HTTPS for mobile testing.

Option 1: ngrok (Recommended)

Stable subdomain, no password prompts.

# Install
brew install ngrok  # or download from ngrok.com

# Expose your dev server
ngrok http 3000

# Output:
# https://abc123.ngrok-free.app → http://localhost:3000

1. Copy the https://...ngrok-free.app URL
2. Add it to your Application’s Allowed Origins in the dashboard
3. Open it on your phone’s browser
4. Test passkey registration/authentication

Option 2: Cloudflare Tunnel

No account needed, but URL changes every session.

# Install
brew install cloudflared

# Expose
cloudflared tunnel --url http://localhost:3000

Testing checklist

• HTTPS URL accessible from phone
• Origin added to Allowed Origins in dashboard
• SDK configured with correct appId and publishableKey
• sandbox: false (sandbox skips WebAuthn, not useful for real device testing)

Common issues

“Passkey not found” on mobile: Passkeys registered on desktop may not be available on mobile unless synced (iCloud Keychain, Google Password Manager). Register a new passkey on the mobile device.

“SecurityError” on mobile: The page is not served over HTTPS. Make sure you’re using the tunnel URL.

iPhone Safari not showing passkey prompt: Safari requires user interaction (a click/tap) to trigger WebAuthn. Ensure register() or authenticate() is called from a user gesture.