AuthKit passkeys

Enable passkeys

Passkeys are optional and disabled by default. For local testing, enable the feature and keep the relying-party ID and origins aligned with the browser URL.

PASSKEY_ENABLED=true
PASSKEY_RP_NAME=BuildBaseKit AuthKit-Lite
PASSKEY_RP_ID=localhost
PASSKEY_ALLOWED_ORIGINS=http://localhost:8080,http://localhost:3000

Registration flow

• Authenticate with the password login API and keep the access token in memory.
• GET /webauthn/csrf to establish the ceremony session and read the CSRF header value.
• POST /webauthn/register/options with Bearer authentication and CSRF.
• Pass the returned options to navigator.credentials.create().
• POST the authenticator response to /webauthn/register with the same session, CSRF token, and Bearer token.
• GET /api/users/me/passkeys to confirm the stored credential metadata.

Authentication flow

• GET /webauthn/csrf for the browser ceremony session.
• POST /webauthn/authenticate/options with the username and CSRF token.
• Pass the returned options to navigator.credentials.get().
• POST the assertion to /login/webauthn with the same session and CSRF token.
• Use the returned access and refresh tokens exactly like a password-login response.

Browser responsibilities

The browser must decode and encode WebAuthn binary fields, call navigator.credentials.create() or navigator.credentials.get(), retain the ceremony cookie, and return real authenticator output. Postman can test options endpoints but cannot simulate a successful platform-authenticator ceremony.

Relevant endpoints

Testing and security

• Use the browser API console for successful registration and authentication.
• Use HTTPS in production; localhost is the development exception.
• Set the relying-party ID to the deployed hostname boundary.
• Allow only trusted application origins.
• Do not disable CSRF on the WebAuthn chain.
• Review credential deletion and account recovery rules for your product.