Passkeys
Passkeys are a phishing-resistant alternative to passwords. Instead of typing a password, users authenticate with whatever their device already uses - Face ID, Touch ID, Windows Hello, or a hardware security key like a YubiKey. There’s no password to steal, no password to forget, and no phishing page that can intercept credentials.
Petal Pro ships with passkey support out of the box, and it’s switched on in the stock config/config.exs. Set config :petal_pro, :passkeys_enabled, false to hide the “Sign in with passkey” button. The Passkeys settings screen and its routes stay until you remove them yourself (see “Removing passkeys entirely” below).
Enabling passkeys
The feature flag lives in your config, and it’s already on:
config :petal_pro, :passkeys_enabled, true
With it on, the sign-in page shows a “Sign in with passkey” button, and Settings > Passkeys is where users register their devices.
To check the flag at runtime:
PetalPro.passkeys_enabled?()
Custom domain config
By default, passkeys are scoped to the host of your endpoint URL. This is the rp_id (relying party ID) in WebAuthn terms - it determines which domains a passkey is valid for.
Most of the time you don’t need to touch this. If you’re running on a subdomain and want passkeys to work across the whole domain (e.g., register on app.example.com and sign in on example.com), set these explicitly:
config :petal_pro,
passkeys_rp_id: "example.com",
passkeys_origin: "https://app.example.com"
passkeys_rp_id is the domain passkeys are scoped to. passkeys_origin is the full origin your app is served from. In production, set these via environment variables if your domain isn’t hardcoded.
⚠️ Warning: A passkey registered on one origin won't work on another. If you change passkeys_rp_id in production, existing passkeys will stop working. Get this right before users start registering.
How it works for users
Registering a passkey
Users manage their passkeys from Settings > Passkeys at /app/users/passkeys. They can:
- Register up to 5 passkeys
- Give each passkey a name (e.g. “MacBook Touch ID”, “iPhone Face ID”)
- Delete passkeys they no longer need
When registering, the browser prompts for the local authenticator - Face ID, fingerprint, PIN, or a hardware key. The private key never leaves the device. Petal Pro stores a public key credential in the user_passkeys table.
Once registered, the Passkeys settings screen shows all your passkeys with the option to toggle 2FA mode or remove individual keys.
Signing in
When passkeys are enabled, the sign-in page shows a “Sign in with passkey” button. The user clicks it, the browser presents available passkeys for the site, and they authenticate with their device. No password needed.
The relevant routes:
GET /auth/passkey/challenge # hands the browser a challenge to sign
POST /auth/sign-in/passkey # checks the passkey and signs the user in
The sign-in POST is limited to 10 a minute per client address (the one PetalProWeb.ClientIp resolves). Since 4.5.2 that limit only applies when CLIENT_IP_HEADER or TRUSTED_PROXY_HOPS is set and the request’s address came from it. Without either, every visitor behind a proxy has the proxy’s address, and one caller could hold passkey sign-in shut for everyone, which matters because a passkey is the way in when the password count is used up. A passkey can’t be guessed, so nothing is lost. Since 4.5.1 the challenge isn’t counted, because the sign-in page asks for one on every load, and a refused attempt goes back to the sign-in page with “Too many attempts. Please try again later.” where it used to be a 500. See Rate Limiting.
Primary auth vs 2FA mode
Passkeys work in two modes in Petal Pro:
Primary auth (passwordless) - The user clicks “Sign in with passkey” on the login page. They never touch a password field. This works for any user who has registered at least one passkey.
Second factor (2FA) - After signing in with a password, users with passkey_2fa_preferred: true get redirected to /app/users/passkey-verify to confirm with their passkey instead of a TOTP code. This gives you the convenience of passkeys without fully replacing password login. Until they confirm, an admin can’t impersonate anyone (since 4.5.2).
The passkey_2fa_preferred flag lives on the User schema. Users can toggle it from Settings > Passkeys once they have a passkey registered. You can check it programmatically:
PetalPro.Accounts.passkey_2fa_preferred?(user)
ℹ️ Note: Passkeys and TOTP are independent. A user can have both set up. If passkey_2fa_preferred is true, the passkey prompt takes precedence over the TOTP prompt after password sign-in.
Removing passkeys entirely
If you don’t want passkeys in your app at all, here’s what to clean up:
-
Config - Set
config :petal_pro, :passkeys_enabled, falseinconfig/config.exs. That only hides the “Sign in with passkey” button on the sign-in page. The Passkeys settings screen is still there. -
Schema - If you want to remove the database fields too, drop
user_passkeystable and removepasskey_2fa_preferredfrom theuserstable. You’ll need to write a migration for that. -
Routes - The passkey routes stay registered when the flag is off. In
router.ex, removelive "/users/passkeys", EditPasskeysLiveand the two/users/passkey-verifyroutes. Inroutes/auth_routes.ex, removeget "/passkey/challenge"andpost "/sign-in/passkey". -
UI - Only the “Sign in with passkey” button is gated on
passkeys_enabled?(). To drop the Passkeys nav item, remove:edit_passkeysfrommenu_items/1inlive/user_settings/user_settings_layout_component.exand delete theget_link(:edit_passkeys = name, _current_user)clause inmenus.ex. Then search forpasskeys_enabled?andEditPasskeysLiveto clear out the rest. -
Dependencies - Passkeys are powered by the
waxHex package. If you’re stripping the feature entirely, remove it frommix.exs.
If you just want passkey sign-in off for now, the flag is enough, and you can turn it back on later. Users can still reach Settings > Passkeys until you do steps 3 and 4.