Skip to main content
BioKey lets you turn a fingerprint scan into a cryptographic identity — no passwords, no vendor lock-in, no biometric data stored anywhere.
Requirements: HTTPS or localhost, modern browser (Chrome 100+, Safari 16+, Firefox 119+), and a device with a fingerprint sensor or Face ID.

​
Quick Start: Browser SDK

The fastest way to add BioKey to your app is with the JavaScript SDK.
1

Install the SDK

Add biokey-js to your project:
npm install biokey-js
Or using Bun:
bun add biokey-js
2

Initialize the client

Create a BioKey client instance:
import { BioKeyClient } from 'biokey-js'

const biokey = new BioKeyClient({
  rpId: location.hostname,    // Your domain
  rpName: 'My App'             // Display name shown during enrollment
})
The rpId must match your website’s hostname. BioKey uses WebAuthn under the hood, which enforces same-origin security.
3

Enroll a fingerprint

Trigger the platform authenticator to create an identity:
const identity = await biokey.enroll()

console.log(identity)
// {
//   publicKey: '7f3a9c2e...', // 64-char hex identity key
//   credentialId: 'a1b2c3...',
//   deviceId: '8d4f2a1b...',
//   enrolledAt: 1735689600000,
//   method: 'prf'  // or 'rawid' (fallback)
// }
This triggers your device’s fingerprint scanner or Face ID. The identity is derived from the biometric event and stored in localStorage.
4

Authenticate

Verify the user with their fingerprint:
const result = await biokey.authenticate()

if (result.verified) {
  console.log('Authenticated!', result.publicKey)
  // Grant access to your app
}
Without a server, authentication only verifies locally. For cross-device or multi-session auth, you need the BioKey server.

​
Quick Start: React

For React apps, use the useBioKey hook:
1

Install the React package

npm install biokey-react
2

Use the hook

import { useBioKey } from 'biokey-react'

export function LoginButton() {
  const { identity, isEnrolled, isLoading, enroll, authenticate, error } = useBioKey()

  if (!isEnrolled) {
    return (
      <button onClick={() => enroll()} disabled={isLoading}>
        {isLoading ? 'Scanning...' : 'Enroll Fingerprint'}
      </button>
    )
  }

  return (
    <div>
      <p>Identity: {identity.publicKey.slice(0, 16)}...</p>
      <button onClick={() => authenticate()} disabled={isLoading}>
        {isLoading ? 'Verifying...' : 'Authenticate'}
      </button>
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </div>
  )
}

​
How It Works

BioKey uses the WebAuthn PRF extension (when available) to derive a stable cryptographic key from your fingerprint: 
Fingerprint scan
  → WebAuthn PRF extension (salt: "biokey-prf-v2-salt")
    → 256-bit hardware secret (never leaves authenticator)
      → hex(secret) = your public identity
On platforms without PRF support, BioKey falls back to HKDF-SHA256 key derivation from the WebAuthn credential’s rawId.

Key Derivation

Understand PRF vs rawId-HKDF methods

Security Model

What BioKey protects against (and what it doesn’t)

Server Setup

Add cross-device authentication

Protocol Spec

Full protocol specification (CC0 public domain)

​
Testing Locally

BioKey requires HTTPS or localhost. To test: 
npm create vite@latest my-biokey-app
cd my-biokey-app
npm install biokey-js
npm run dev  # Opens at https://localhost:5173
Mobile testing: Deploy to Vercel, Netlify, or Railway for HTTPS. WebAuthn requires a secure context.

​
Next Steps

1

Install packages

See Installation for all packages and framework-specific setup.
2

Add a server

Enable cross-device auth with biokey-server.
3

Explore examples

Check out full examples with live code.

Build docs developers (and LLMs) love

Get started for freeTalk to us