Passkey

The passkey plugin implements WebAuthn registration and authentication ceremonies. It stores credential IDs, public keys, counters, transports, and device metadata so users can register and sign in with platform or roaming authenticators.

Installation

uv add kernia-passkey

Import path

from kernia_passkey import passkey

Server configuration

auth.py

import os

from kernia import KerniaOptions
from kernia.auth import init
from kernia_passkey import passkey

from .db import adapter

auth = init(KerniaOptions(
    database=adapter,
    secret=os.environ["KERNIA_SECRET"],
    base_url=os.environ["KERNIA_BASE_URL"],
    base_path="/api/auth",
    plugins=(
        passkey(
            rp_id="localhost",
            rp_name="Kernia Demo",
            origin="http://localhost:5173",
        ),
    ),
))

API routes

POST/api/auth/passkey/register/start

Creates WebAuthn registration options for the active user.

POST/api/auth/passkey/register/finish

Verifies the registration response and stores the credential.

POST/api/auth/passkey/authenticate/start

Creates WebAuthn authentication options.

POST/api/auth/passkey/authenticate/finish

Verifies the assertion and creates a session.

GET/api/auth/passkey/list

Lists passkeys registered by the active user.

POST/api/auth/passkey/delete

Deletes one registered passkey for the active user.

Schema impact

Adds a passkey credential table. Generate migrations after installing the standalone package.

Behavior and options

rp_id must match the effective domain. Localhost and production domains need separate settings.
origin must match the browser origin that calls WebAuthn.
Conditional UI requires browser support and frontend feature detection.