Passkeys are cryptographic credentials that replace passwords with biometric authentication (fingerprint, face scan) or device PINs. PropelAuth BYO’s Passkey APIs handle the complex WebAuthn protocol for you, letting you add passwordless authentication, MFA, or both to your application.

Basic Usage

Passkeys work in two phases: registration (saving a user’s passkey) and authentication (validating that passkey later).

Registration

First, your backend generates registration options. Then your frontend uses a WebAuthn library like @simplewebauthn/browser to prompt the user to create a passkey. Finally, you send the result back to your backend to save the passkey.

Node Python

// Backend: Begin the registration process for a specific user
const registrationOptions = await auth.passkeys.startRegistration({...});

# Backend: Begin the registration process for a specific user
registration_options = await client.passkeys.start_registration(...)

          // Backend: Begin the registration process for a specific user
const registrationOptions = await auth.passkeys.startRegistration({...});
        

          # Backend: Begin the registration process for a specific user
registration_options = await client.passkeys.start_registration(...)
        

// Frontend: Create the passkey on the user's device
const credential = await startRegistration({
    optionsJSON: registrationOptions,
});

Node Python

// Backend: Finish the registration
const result = await auth.passkeys.finishRegistration({...});

# Backend: Finish the registration
result = await client.passkeys.finish_registration(...)

          // Backend: Finish the registration
const result = await auth.passkeys.finishRegistration({...});
        

          # Backend: Finish the registration
result = await client.passkeys.finish_registration(...)
        

Authentication

To authenticate, your backend sends passkey authentication options to the frontend. The user validates their passkey on their device, generating a signature. Your backend then verifies this signature to complete the authentication.

Node Python

// Backend: Begin the validation process for a specific user
const authenticationOptions = await auth.passkeys.startAuthentication({...});

# Backend: Begin the validation process for a specific user
authentication_options = await client.passkeys.start_authentication(...)

          // Backend: Begin the validation process for a specific user
const authenticationOptions = await auth.passkeys.startAuthentication({...});
        

          # Backend: Begin the validation process for a specific user
authentication_options = await client.passkeys.start_authentication(...)
        

// Frontend: Sign the challenge with the user's passkey
const credential = await startAuthentication({
    optionsJSON: authenticationOptions,
});

Node Python

// Backend: Finish the validation
const result = await auth.passkeys.finishAuthentication({...});

# Backend: Finish the validation
result = await client.passkeys.finish_authentication(...)

          // Backend: Finish the validation
const result = await auth.passkeys.finishAuthentication({...});
        

          # Backend: Finish the validation
result = await client.passkeys.finish_authentication(...)
        

See the complete tutorial for step-by-step implementation details.

Configuring Passkey Settings

The passkey_config.jsonc file controls passkey behavior, including limits and security settings.

passkey_config.jsonc

{
  // Hostname for the WebAuthn relying party
  // Examples: "example.com", "localhost:3000", "app.example.com"
  "hostname": "example.com",

  // Maximum number of passkeys allowed per user (default: 5, max: 10)
  "max_passkeys_per_user": 5
}

Supporting Multiple Passkeys

Users can register multiple passkeys (e.g., one on their phone, another on their laptop). Set the limit with max_passkeys_per_user in your config file.

During authentication, PropelAuth BYO automatically sends all the user’s registered passkey identifiers to the frontend. The WebAuthn library handles letting the user choose which passkey to use.

Managing Passkeys

Users may need to remove old passkeys when they get new devices or lose access to existing ones.

Programmatically:

• Deregister Passkey - Remove a specific passkey
• Deregister All Passkeys For User - Remove all passkeys for a user

Via Dashboard: You can also manage passkeys directly in the PropelAuth BYO Dashboard: