Skip to main content

Passkey Authentication

Zyphe provides full FIDO2/WebAuthn support for passwordless authentication, allowing users to register and authenticate using biometric sensors, security keys, or mobile devices.

How It Works​

Registration Flow​

  1. Initiation: The client calls the registration start endpoint to receive a cryptographic challenge. This requires an active JWT session.
  2. Credential Creation: The user's device generates a new passkey and signs the challenge.
  3. Completion: The client submits the signed credential to the registration endpoint. The system verifies the signature and stores the public key.

Authentication Flow​

  1. Initiation: The client requests an authentication challenge by providing either a specific credential ID or the user's email.
  2. Assertion: The user's device signs the challenge using the previously registered passkey.
  3. Completion: The client submits the authentication response. Upon successful verification, the system returns a session token or verification request ID.

API Endpoints​

MethodPathDescription
GET/auth/register-passkey/startInitiates passkey registration. Returns a challenge. Requires JWT authentication.
POST/auth/register-passkeyCompletes registration with the signed credential. Accepts registrationResponse and optional prfSalt.
POST/auth/authenticate-passkey/startInitiates authentication. Accepts optional credentialId or email. Returns challenge and options.
POST/auth/authenticate-passkeyCompletes authentication. Accepts authenticationResponse and tokenType (Bearer or VerificationRequest).

Security Features​

  • Challenge Expiry: Registration and authentication states are cached for 300 seconds (5 minutes). Challenges must be completed within this window.
  • PRF Support: Supports the Pseudo Random Function (PRF) extension for WebAuthn, enabling client-side vault encryption.
  • Vault Integration: Upon registration, the system automatically creates or unlocks the user's secure vault using a passkey-derived key.
  • Token Types: Supports Bearer tokens for dashboard access (invalidates cache) and VerificationRequest tokens for identity verification flows (retains cache for vault access).