Viewing latest docs.
Switch version:

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/config.exs
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/runtime.exs
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.

Passkey registration form

Once registered, the Passkeys settings screen shows all your passkeys with the option to toggle 2FA mode or remove individual keys.

Security settings with passkeys registered

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.

Sign in page with passkey button

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:

  1. Config - Set config :petal_pro, :passkeys_enabled, false in config/config.exs. That only hides the “Sign in with passkey” button on the sign-in page. The Passkeys settings screen is still there.

  2. Schema - If you want to remove the database fields too, drop user_passkeys table and remove passkey_2fa_preferred from the users table. You’ll need to write a migration for that.

  3. Routes - The passkey routes stay registered when the flag is off. In router.ex, remove live "/users/passkeys", EditPasskeysLive and the two /users/passkey-verify routes. In routes/auth_routes.ex, remove get "/passkey/challenge" and post "/sign-in/passkey".

  4. UI - Only the “Sign in with passkey” button is gated on passkeys_enabled?(). To drop the Passkeys nav item, remove :edit_passkeys from menu_items/1 in live/user_settings/user_settings_layout_component.ex and delete the get_link(:edit_passkeys = name, _current_user) clause in menus.ex. Then search for passkeys_enabled? and EditPasskeysLive to clear out the rest.

  5. Dependencies - Passkeys are powered by the wax Hex package. If you’re stripping the feature entirely, remove it from mix.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.