> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Passkeys initial research (passkeys-server + @laravel/passkeys)

> Initial research into laravel/passkeys-server (PHP) and @laravel/passkeys (npm). Covers installation, User model integration, routes, configuration, events, the frontend API, typed errors, and SSR support.

<Info>
  This article is initial research based on the READMEs of `laravel/passkeys-server` and `laravel/passkeys`. Both packages are still in an untagged development stage (as of April 2026).
</Info>

## What are these packages?

Laravel's official organization has published two packages for implementing passwordless authentication (WebAuthn / passkeys).

* Server side (PHP): [`laravel/passkeys-server`](https://github.com/laravel/passkeys-server)
* Client side (JavaScript): [`@laravel/passkeys`](https://github.com/laravel/passkeys)

Combining the two lets you implement passkey registration and passkey login end-to-end in a Laravel app.

## Server side: `laravel/passkeys-server`

### Installation and initial setup

<Steps>
  <Step title="Add the PHP package">
    ```bash theme={null}
    composer require laravel/passkeys
    ```
  </Step>

  <Step title="Publish and run migrations">
    ```bash theme={null}
    php artisan vendor:publish --tag=passkeys-migrations
    php artisan migrate
    ```
  </Step>

  <Step title="Add the trait and contract to your User model">
    ```php theme={null}
    use Laravel\Passkeys\Contracts\PasskeyUser;
    use Laravel\Passkeys\PasskeyAuthenticatable;

    class User extends Authenticatable implements PasskeyUser
    {
        use PasskeyAuthenticatable;
    }
    ```
  </Step>
</Steps>

You can also publish the configuration file if needed.

```bash theme={null}
php artisan vendor:publish --tag=passkeys-config
```

### Routes registered automatically

| Category          | Method   | Route                       | Purpose                      |
| ----------------- | -------- | --------------------------- | ---------------------------- |
| Login (guest)     | `GET`    | `/passkeys/login/options`   | Fetch authentication options |
| Login (guest)     | `POST`   | `/passkeys/login`           | Verify passkey and log in    |
| Confirm (auth)    | `GET`    | `/passkeys/confirm/options` | Fetch confirmation options   |
| Confirm (auth)    | `POST`   | `/passkeys/confirm`         | Confirm passkey              |
| Management (auth) | `GET`    | `/user/passkeys/options`    | Fetch registration options   |
| Management (auth) | `POST`   | `/user/passkeys`            | Save a new passkey           |
| Management (auth) | `DELETE` | `/user/passkeys/{passkey}`  | Delete a passkey             |

### Key options in `config/passkeys.php`

* `relying_party_id`
* `allowed_origins`
* `user_handle_secret`
* `timeout`
* `guard`
* `middleware`
* `throttle`
* `redirect`

### Events

The package dispatches the following events.

* `PasskeyRegistered`
* `PasskeyVerified`
* `PasskeyDeleted`

### Customization points

<AccordionGroup>
  <Accordion title="LoginAuthorizationCallback (login authorization)">
    `Passkeys::authorizeLoginUsing()` lets you control login authorization after successful verification. To block login, return `false` or throw a `ValidationException`.
  </Accordion>

  <Accordion title="CustomActions (replace WebAuthn processing)">
    Extend and bind `GenerateRegistrationOptions` / `GenerateVerificationOptions` / `StorePasskey` / `VerifyPasskey` / `DeletePasskey` to the service container to change behavior.
  </Accordion>

  <Accordion title="CustomResponses (replace responses)">
    Implement contracts like `PasskeyLoginResponse` to change success responses (JSON, redirect, etc.) to match your app's needs.
  </Accordion>
</AccordionGroup>

## Client side: `@laravel/passkeys`

`@laravel/passkeys` is a JavaScript client that handles browser-side WebAuthn ceremonies.

### Installation

```bash theme={null}
npm install @laravel/passkeys
```

### Basic API

```js theme={null}
import { Passkeys } from "@laravel/passkeys";

await Passkeys.register({ name: "My MacBook" });
await Passkeys.verify();
```

### Framework helpers

* React: `usePasskeyVerify`, `usePasskeyRegister` from `@laravel/passkeys/react`
* Vue: `usePasskeyVerify`, `usePasskeyRegister` from `@laravel/passkeys/vue`
* Svelte: `usePasskeyVerify`, `usePasskeyRegister` from `@laravel/passkeys/svelte`

### Passkey autofill

Passing `autofill: true` allows the browser's passkey picker to appear on inputs with `autocomplete="... webauthn"`. In unsupported environments or when the user cancels, it falls back to the normal flow.

### Typed errors

The README exposes the following error classes.

* `NotSupportedError`
* `UserCancelledError`
* `PasskeyExistsError`
* `PasskeyError` (base class)

### SSR support

WebAuthn is a browser API, but each framework's hooks are SSR-safe. On the server, `isSupported` is treated as `false` and updates to the actual browser state after mounting.

## Summary

* Combining `laravel/passkeys-server` (PHP) and `@laravel/passkeys` (JS) lets you build a fully Laravel-native passkey authentication stack.
* Both are still in an untagged development stage but, as part of Laravel's official ecosystem, they're likely to become a standard authentication method going forward.
* If you're adopting early, design around the routes, configuration, error handling, and customization extension points in the README to stay safe.

<Info>
  Passkeys were later **officially added as a feature of Laravel Fortify**. To enable passkeys via Fortify, use `Features::passkeys()` instead of installing `laravel/passkeys-server` directly. See [Laravel Fortify and starter kits](/en/advanced/fortify) for details.
</Info>

<Card title="laravel/passkeys-server" icon="github" href="https://github.com/laravel/passkeys-server">
  See the latest README and implementation for the server-side package.
</Card>

<Card title="@laravel/passkeys" icon="github" href="https://github.com/laravel/passkeys">
  See the latest README and API for the client-side package.
</Card>

<Card title="Laravel Fortify and starter kits" icon="shield-check" href="/en/advanced/fortify">
  Learn how to enable passkeys via Fortify and how it relates to the starter kits.
</Card>


## Related topics

- [Laravel Chisel — a post-install script library for starter kits](/en/blog/chisel-introduction.md)
- [April 2026 Laravel updates](/en/blog/changelog/202604.md)
- [Laravel Fortify and Starter Kits](/en/advanced/fortify.md)
- [Migration guide from laravel/ui to Fortify](/en/blog/ui-to-fortify.md)
- [Starter kits](/en/starter-kits.md)