Passkey Documentation

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 Go

// 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

result, err := client.Passkeys.StartRegistration(ctx, byo.StartPasskeyRegistrationCommand{

UserID:          userID,

EmailOrUsername: email,

})

if err != nil {

log.Fatal(err)

}

fmt.Println(string(result.RegistrationOptions))

// Frontend: Create the passkey on the user's device

const credential = await startRegistration({

optionsJSON: registrationOptions,

});

Node Python Go

// Backend: Finish the registration

const result = await auth.passkeys.finishRegistration({...});

# Backend: Finish the registration

result = await client.passkeys.finish_registration(...)

// Backend: Finish the registration

_, err := client.Passkeys.FinishRegistration(ctx, byo.FinishPasskeyRegistrationCommand{

UserID:    userID,

PublicKey: publicKey,

})

if err != nil {

log.Fatal(err)

}

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 Go

// 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

result, err := client.Passkeys.StartAuthentication(ctx, byo.StartPasskeyAuthenticationCommand{

UserID: userID,

})

if err != nil {

log.Fatal(err)

}

fmt.Println(string(result.AuthenticationOptions))

// Frontend: Sign the challenge with the user's passkey

const credential = await startAuthentication({

optionsJSON: authenticationOptions,

});

Node Python Go

// Backend: Finish the validation

const result = await auth.passkeys.finishAuthentication({...});

# Backend: Finish the validation

result = await client.passkeys.finish_authentication(...)

// Backend: Finish the validation

_, err := client.Passkeys.FinishAuthentication(ctx, byo.FinishPasskeyAuthenticationCommand{

UserID:    userID,

PublicKey: publicKey,

})

if err != nil {

log.Fatal(err)

}

Configuring Passkey Settings

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

{

// 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: