Skip to main content
The authenticate() function verifies a previously enrolled biometric identity by re-deriving the key and comparing it to the stored public key.

​
Function Signature

import { authenticate } from 'biokey-core'

const result = await authenticate(identity, rpId)

​
Parameters

​
identity
object
required
The identity object returned from enroll()
​
identity.credentialId
string
required
Hex-encoded credential ID
​
identity.publicKey
string
required
Hex-encoded public key to verify against
​
identity.method
'prf' | 'rawid'
required
Derivation method used during enrollment
​
rpId
string
required
Relying Party ID - must match the ID used during enrollment

​
Return Value

Returns a Promise that resolves to a verification result:
​
verified
boolean
Always true when the function returns successfully (throws error on failure)
​
publicKey
string
Re-derived public key (hex-encoded)
​
method
'prf' | 'rawid'
  • 'prf': PRF extension was used to re-derive the key
  • 'rawid': HKDF fallback was used

​
How It Works

  1. WebAuthn Get: Requests credential assertion with PRF extension
  2. Re-Derivation: Uses the same method (PRF or rawId-HKDF) to re-derive the key
  3. Verification: Compares re-derived key against stored identity.publicKey
  4. Throws on Mismatch: Raises an error if keys don’t match or assertion fails

​
Example

import { authenticate } from 'biokey-core'

// Retrieve stored identity
const identity = JSON.parse(localStorage.getItem('biokey-identity'))

try {
  const result = await authenticate(identity, 'example.com')
  
  console.log('Authentication successful!')
  console.log('Verified:', result.verified) // true
  console.log('Method:', result.method) // 'prf' or 'rawid'
  
  // User is authenticated - proceed with app logic
  redirectToApp()
} catch (error) {
  console.error('Authentication failed:', error.message)
  // Handle failure - show error, retry, etc.
}

​
Error Handling

The function throws errors in these cases: 
// No identity provided
throw new Error('No enrolled identity provided.')

// No assertion returned from authenticator
throw new Error('Authentication failed — no assertion returned.')

// PRF key mismatch
throw new Error('PRF key mismatch — identity verification failed.')

// rawId-HKDF key mismatch
throw new Error('Key mismatch — identity verification failed.')

​
WebAuthn Configuration

The function configures WebAuthn assertions with:
  • Challenge: 32 random bytes
  • Allowed Credentials: Only the provided credential ID
  • User Verification: Required
  • PRF Extension: Uses evalByCredential with the same salt as enrollment
  • Timeout: 60 seconds

​
Security Notes

  • The function verifies that the re-derived key matches the stored public key
  • PRF output is hardware-backed and never leaves the authenticator
  • rawId fallback is best-effort for environments without PRF support
  • Always use the same rpId for enrollment and authentication

​
Source Reference

See /packages/biokey-core/src/authenticate.js:9

Build docs developers (and LLMs) love

Get started for freeTalk to us