@laravel/passkeys

A JavaScript client for passkey authentication designed to work with Laravel applications. It provides a fluent API for browser-side WebAuthn ceremonies (registration and authentication).

Installation

npm install @laravel/passkeys

Quick Start

import { Passkeys } from "@laravel/passkeys";

// Register a new passkey (authenticated user)
await Passkeys.register({ name: "MacBook Pro" });

// Verify passkey
await Passkeys.verify();

Framework Helpers

React

import { useState } from "react";
import { usePasskeyVerify, usePasskeyRegister } from "@laravel/passkeys/react";

// Login
function LoginPage() {
    const { verify, isLoading, error, isSupported } = usePasskeyVerify({
        autofill: true,
        onSuccess: (response) => {
            if (response.redirect) {
                window.location.href = response.redirect;
            }
        },
    });

    return (
        <div>
            {/* Add webauthn and set autofill: true to show passkeys in the input */}
            <input type="text" autoComplete="email webauthn" />

            <button onClick={verify} disabled={!isSupported || isLoading}>
                {isLoading ? "Authenticating..." : "Sign in with passkey"}
            </button>
            {error && <p className="error">{error}</p>}
        </div>
    );
}

// Register
function RegisterForm() {
    const [name, setName] = useState("");
    const { register, isLoading, error } = usePasskeyRegister();

    return (
        <div>
            <input
                value={name}
                onChange={(e) => setName(e.target.value)}
                placeholder="Passkey name"
            />
            <button
                onClick={() => register(name)}
                disabled={isLoading || !name}
            >
                {isLoading ? "Registering..." : "Add passkey"}
            </button>
            {error && <p className="error">{error}</p>}
        </div>
    );
}

Vue

<script setup>
import { ref } from "vue";
import { usePasskeyVerify, usePasskeyRegister } from "@laravel/passkeys/vue";
import { router } from "@inertiajs/vue3";

// Login
const {
    verify,
    isLoading: verifyLoading,
    error: verifyError,
} = usePasskeyVerify({
    autofill: true,
    onSuccess: (response) => {
        if (response.redirect) {
            router.visit(response.redirect);
        }
    },
});

// Register
const name = ref("");
const {
    register,
    isLoading: registerLoading,
    error: registerError,
} = usePasskeyRegister();
</script>

<template>
    <!-- Include webauthn and set autofill: true to show passkeys in the input -->
    <input type="text" autocomplete="email webauthn" />

    <button @click="verify" :disabled="verifyLoading">
        {{ verifyLoading ? "Authenticating..." : "Sign in with passkey" }}
    </button>
    <p v-if="verifyError" class="error">{{ verifyError }}</p>

    <!-- Register -->
    <input v-model="name" placeholder="Passkey name" />
    <button @click="register(name)" :disabled="registerLoading || !name">
        {{ registerLoading ? "Registering..." : "Add passkey" }}
    </button>
    <p v-if="registerError" class="error">{{ registerError }}</p>
</template>

Svelte

Access the returned values through the hook object (don't destructure), so Svelte's reactivity stays live:

<script>
    import { usePasskeyVerify, usePasskeyRegister } from "@laravel/passkeys/svelte";

    const verify = usePasskeyVerify({
        autofill: true,
        onSuccess: (response) => {
            if (response.redirect) window.location.href = response.redirect;
        },
    });

    const register = usePasskeyRegister();
    let name = $state("");
</script>

<!-- Include webauthn and set autofill: true to show passkeys in the input -->
<input type="email" autocomplete="email webauthn" />

<button onclick={verify.verify} disabled={!verify.isSupported || verify.isLoading}>
    {verify.isLoading ? "Authenticating..." : "Sign in with passkey"}
</button>
{#if verify.error}<p class="error">{verify.error}</p>{/if}

<input bind:value={name} placeholder="Passkey name" />
<button
    onclick={() => register.register(name)}
    disabled={register.isLoading || !name}
>
    {register.isLoading ? "Registering..." : "Add passkey"}
</button>
{#if register.error}<p class="error">{register.error}</p>{/if}

Server-Side Rendering

WebAuthn is a browser-only API. The framework hooks are SSR-safe: on the server and during hydration, isSupported renders as false, then updates to the real value after the component mounts. This avoids hydration warnings without any user-visible flash — in Vue and Svelte the post-mount update runs as a microtask before the browser paints; in React it's handled by useSyncExternalStore (client-only apps see the real value on the first render).

If you need the synchronous value outside a component lifecycle, call Passkeys.isSupported() directly — it returns false under Node without throwing.

Passkey Autofill

When autofill: true is passed, the hook asks the browser to surface saved passkeys inside the native credential-picker dropdown. The browser attaches that dropdown to an <input> whose autocomplete attribute includes the webauthn token (typically alongside username or email). If no such input is mounted by the time the autofill request starts, the dropdown has nowhere to anchor and silently shows nothing — no error, no console warning, just no picker.

If the browser doesn't support autofill (checked via isAutofillSupported()) or the user dismisses the picker, the hook falls back to doing nothing and your explicit "Sign in with passkey" button still works.

Core API

Public Methods

| Method | Description | | ----------------------------- | ------------------------------------------------- | | configure(options) | Configure the passkeys client | | isSupported() | Check if the browser supports passkeys | | isAutofillSupported() | Check if the browser supports passkey autofill | | register({ name, routes? }) | Register a new passkey for the authenticated user | | verify(options?) | Verify a passkey | | autofill(options?) | Enable passkey autofill on the current page | | cancel() | Cancel any pending passkey operation |

Client Configuration

Use configure() to adjust the fetch options used for passkey requests:

Passkeys.configure({
    fetch: {
        credentials: "include",
        headers: {
            "X-Tenant": tenantId,
        },
    },
});

Expected Endpoints

This package handles communication with your Laravel application and expects the following endpoints:

Authentication (Guest)

| Method | Route | Purpose | | ------ | ------------------------- | ---------------------------------- | | GET | /passkeys/login/options | Fetch authentication options | | POST | /passkeys/login | Verify credential and authenticate |

Registration (Authenticated)

| Method | Route | Purpose | | ------ | ------------------------ | -------------------------- | | GET | /user/passkeys/options | Fetch registration options | | POST | /user/passkeys | Store new passkey |

Per-Call Route Overrides

await Passkeys.register({
    name: "MacBook Pro",
    routes: {
        options: "/user/security/passkeys/options",
        submit: "/user/security/passkeys",
    },
});

await Passkeys.verify({
    routes: {
        options: "/passkeys/confirm/options",
        submit: "/passkeys/confirm",
    },
});

register(), verify(), and autofill() all use:

type RouteOverrides = {
    routes?: {
        options?: string;
        submit?: string;
    };
};

React / Vue / Svelte Route Overrides

The usePasskeyVerify adapters accept:

usePasskeyVerify({
    autofill: true,
    routes: {
        options: "/passkeys/confirm/options",
        submit: "/passkeys/confirm",
    },
    onSuccess: (response) => {
        if (response.redirect) {
            window.location.href = response.redirect;
        }
    },
});

The usePasskeyRegister adapters accept:

usePasskeyRegister({
    routes: {
        options: "/user/security/passkeys/options",
        submit: "/user/security/passkeys",
    },
    onSuccess: () => {
        window.location.reload();
    },
});

Typed Errors

All ceremony failures are converted to PasskeyError subclasses so you can branch on error type:

| Class | Thrown when | | -------------------- | ------------------------------------------------------------ | | NotSupportedError | The browser does not support WebAuthn | | UserCancelledError | The user dismissed the native prompt | | PasskeyExistsError | A passkey for this account/device is already registered | | InvalidDomainError | Passkeys are used from an invalid domain | | PasskeyError | Base class; used for server errors and any unmapped failures |

Passkeys.register() and Passkeys.verify() throw these directly. The framework adapters expose them two ways: the onError callback receives the typed instance, and each hook returns an errorInstance field (alongside the string error) so you can branch from markup:

import { PasskeyExistsError } from "@laravel/passkeys";
import { usePasskeyRegister } from "@laravel/passkeys/react";

const { register, error, errorInstance } = usePasskeyRegister();

// ...
{
    errorInstance instanceof PasskeyExistsError ? (
        <p>You already registered a passkey on this device.</p>
    ) : error ? (
        <p className="error">{error}</p>
    ) : null;
}

Type Compatibility

This package uses TypeScript types from @simplewebauthn/browser. These types are fully compatible with the JSON output from the web-auth/webauthn-lib PHP package.

Package Exports

| Entry Point | Exports | | -------------------------- | ---------------------------------------- | | @laravel/passkeys | Passkeys | | @laravel/passkeys/react | usePasskeyVerify, usePasskeyRegister | | @laravel/passkeys/vue | usePasskeyVerify, usePasskeyRegister | | @laravel/passkeys/svelte | usePasskeyVerify, usePasskeyRegister |