Repository navigation
Passkeys
A passkey (WebAuthn) is a key pair kept by the person's device (Touch ID, Windows Hello, Android, a security key or
a password manager) and unlocked with its biometrics or PIN. The private key never leaves the device and a passkey works
only on the domain it was made for: it cannot be phished or replayed. Caligrafy\Passkey (on
lbuchs/webauthn) checks them on the server, PasskeyClient
(public/js/services/passkey.js) runs them in the browser, and Route::auth(['passkeys' => true]) declares the four
endpoints. In Route::auth since 2.19.0.
"people can add a passkey once signed in, and sign in with it"
For face sign-in with liveness and passkeys, say "face sign-in with liveness and passkeys": Claude follows the plugin's face login recipe (Face detection and face login).
Check
- Signed in, adding a passkey answers
201and a row appears inpasskeys. - Signed out, the passkey signs you in, and
AuthRoutes::signedInBy()answerspasskey.
Before you start: the authentication module (Auth::authentication('User', 'users'); in web.php).
-
The table. Add it with a migration
(
php caligrafer.php migrate make add_passkeys), with the statement of the face login recipe:thenCREATE TABLE IF NOT EXISTS passkeys ( id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, user_id INT NOT NULL, credential_id VARCHAR(255) NOT NULL, -- base64url public_key TEXT NOT NULL, -- PEM sign_count INT UNSIGNED NOT NULL DEFAULT 0, name VARCHAR(64) NOT NULL DEFAULT 'Passkey', transports VARCHAR(255) NULL, aaguid CHAR(32) NULL, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, last_used_at DATETIME NULL, CONSTRAINT uq_passkeys_credential_id UNIQUE (credential_id), CONSTRAINT fk_passkeys_user_id FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
php caligrafer.php migrate. -
The endpoints, in
application/config/routing/web.php:It declaresRoute::auth(['home' => '/', 'passkeys' => true]);
POST /passkey/register/options,/passkey/register(signed in),/passkey/login/optionsand/passkey/login. -
The browser. Load
passkey.js(APP_SERVICE_ROOTis the address ofpublic/js/services/) and call the endpoints with the session'sX-CSRF-Tokenheader. In a client app page,apiHeaders()gives it:// <script src="<?php echo APP_SERVICE_ROOT.'passkey.js'; ?>"></script> const config = { headers: apiHeaders() }; // the session and its X-CSRF-Token const options = (await axios.post(env.home + 'passkey/register/options', {}, config)).data; await axios.post(env.home + 'passkey/register', await PasskeyClient.create(options), config); const login = (await axios.post(env.home + 'passkey/login/options', {}, config)).data; await axios.post(env.home + 'passkey/login', await PasskeyClient.get(login), config);
PasskeyClient.supported()says whether the browser has passkeys at all. -
In production, set in
.env(they are not in.env.example):Without them the request host is used, which is fine onPASSKEY_RP_ID=example.com PASSKEY_ORIGIN=https://www.example.com
http://localhost. Passkeys needhttps, except onlocalhost.
| Endpoint | Who | Answers |
|---|---|---|
POST /passkey/register/options |
signed in |
200 the options for PasskeyClient.create(); 401 Sign in first
|
POST /passkey/register |
signed in |
201 {"passkey": {"name": ...}} (the optional name field, Passkey by default) |
POST /passkey/login/options |
anyone |
200 the options for PasskeyClient.get(): any passkey of the site, no username to type |
POST /passkey/login |
anyone |
200 {"user": {"id", "username", "permissions"}}, a new session id and CSRF token, signed in by passkey; 401 Unknown account
|
Every one needs the X-CSRF-Token header (403 without it). A passkey error answers its status (400 a failed
registration, 409 This passkey is already registered, 401 a failed sign-in) with {"error": ...}. The level
option of Route::auth applies: someone below it is refused like an unknown account.
Registration (signed in): registrationOptions($id, $username) -> navigator.credentials.create() -> register($response, $id)
Sign-in: authenticationOptions([$id]) -> navigator.credentials.get() -> authenticate($response) returns the user id
-
new Passkey($rpName = APP_NAME, $rpId = PASSKEY_RP_ID or the request host, $origin = PASSKEY_ORIGIN or APP_PROTOCOL://host, $table = 'passkeys'). -
registrationOptions($userId, $userName, $displayName = null): the user id is the WebAuthn user handle, never an email or a name.register($response, $userId, $name = null)stores the credential and returns it without its public key.authenticationOptions($userId = null):nulllets the browser offer any discoverable passkey of the site.authenticate($response)returns the id of the user who owns the passkey.remove($userId, $credentialId),credentials($userId). - The challenge of each ceremony is kept in the session, used once, and expires after
$timeout(120 s).$userVerificationand$residentKeyarerequired. - To store the credentials elsewhere, extend
Passkeyand overridecredentials(),findCredential(),saveCredential()andtouchCredential().
Every method: API: Caligrafy\Passkey.
-
Route::auth(['passkeys' => true])and the face login recipe's passkey routes both declared: the recipe'sRoute::actionlines replace it; declare one of them. -
No
PASSKEY_RP_ID/PASSKEY_ORIGINin production: the request host is used; set both (G42). -
http://on a server: passkeys needhttps, except onlocalhost. -
Calling the endpoints without
X-CSRF-Token:403.
-
Sign-in, users and tokens:
Route::auth - Face detection and face login
-
How to sign in through another site:
AuthRoutes::signedInBy() - API: Caligrafy\Passkey
Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.
Why Caligrafy: the benefits, the measurements, and what it is not yet
-
Quickstart with Claude: describe it, approve it, ship it
or the Quickstart: the same three steps by hand, in 5 minutes
- How Caligrafy works: the ideas in 5 minutes
- Your first capability: build a feature, page included
-
Capabilities in depth
-
#[Capability]: every option - Scheduled jobs: capabilities on a timer
- Notifications: web push and email
- Background jobs: capabilities run later
- Migrations: database changes, in order
- The cache
-
Testing your app
- Dependency injection
- Validation rules
-
Web pages
- Views and page components
- Design styles: another look, one setting
- Declarative routes: every request, in one line
-
Route::page·Route::form·Route::auth·Route::webhook·Route::download·Route::redirect·Route::action·Route::snap· capability routes - How to export a list as CSV
- Controllers: moving one to a declared route · how to, step by step
- Forms and helpers
-
Vue apps
-
Mobile and tablet
-
REST API
-
AI agents
-
Snap Cards and the assistant
- Payments: Stripe and crypto
- Face detection and face login
- OpenAI: chat and images · Assistants
- Open models: Llama, Mistral...
- Chatbots with Watson
- Machine learning in the browser
- Metadata and social cards · search and analytics
-
Putting it online: the production image, the database at every start
-
API reference: every class and method
-
Routing ·
Route·AuthRoutes· pages ·Controller· capabilities -
Data ·
Model·Query· sign-in · jobs ·Notify· payments · AI -
Interfaces · Snap ·
Snap\Cards·Snap\Conversation· testing · tooling · helper functions
-
Routing ·
-
Caligrafer: every command
- Project · build · data · agents · jobs and tests · maintenance · deploy
- Installation, configuration and Caligrafer
- Routing · Request · Controllers · Views
- Vue: flow of information · routes · validations
- Security and upgrading
- Release notes: 2.26 · 2.25 · 2.24 · 2.23 · 2.22 · 2.21 · 2.20 · 2.19 · 2.18 · 2.17 · 2.16 · 2.15 · 2.14 · 2.13 · 2.12 · 2.11 · 2.10 · 2.9 · 2.8 · 2.7 · 2.6 · 2.5 · 2.4 · 2.3 · 2.1 · October 2026 · changelog
- Testing Caligrafy (contributors)