Signet
Sign in

Guide

WebAuthn setup

Passkeys and platform authenticators (Touch ID, Face ID, Windows Hello, security keys) let users sign in without typing a TOTP code. This deployment reads oneACCESS_WEBAUTHN_SECRET JSON value; it may contain one credential or several (see byHost / credentials below) so each hostname you use can have its own passkey.

You can run WebAuthn-only flows when the deployment is configured for it, or keep TOTP as a backup—see TOTP setup and Environment variables.

Relying party ID (rpId)

rpId must equal the host users see in the address bar for that deployment (no scheme, no path). Use localhost for local HTTP dev; production must be served over HTTPS with a hostname that exactly matches the registered credential. If you open the same deployment under several hostnames (e.g. localhost and vercel-2fa.vercel.app), register once per host and store them together using the byHost shape in ACCESS_WEBAUTHN_SECRET — see Environment variables.

Register

  1. Open /webauthn
  2. Username matches ACCESS_USERNAME
  3. Pick a display name you will recognize later (for example "MacBook Touch ID" or "YubiKey 5C")
  4. When the browser prompts, choose platform authenticator, passkey sync (if offered), or a roaming security key
Open WebAuthn tool

Save credential JSON

After registration, copy the exported JSON object into ACCESS_WEBAUTHN_SECRET as a single line. It includes Base64 fields such as credentialID and publicKey plus rpId and username for sanity checks.

{ "credentialID": "...", "publicKey": "...", "rpId": "localhost", "username": "admin" }

On Vercel, paste via the dashboard or CLI; escape quotes if your shell requires it. Treat this blob like a password—anyone with it can mint assertions if they also know your password and can reach the login page.

Operations & recovery

  • HTTPS is required in production; localhost is exempt for development only
  • Credentials are device-bound — new laptop or browser profile needs a new registration (and env update) unless you use synced passkeys from the same platform account
  • Keep TOTP configured as fallback when hardware is lost or unavailable
  • If login fails after a domain change, re-run registration on the new origin and replace the env JSON
WebAuthn Setup - Getting Started