Passkeys

Let people sign in with the fingerprint, face or screen lock of their device, as the first step or as a phishing-resistant second factor.

A passkey is a WebAuthn credential: a key pair whose private half never leaves the person’s device or password manager. Signing in means unlocking the device the way they already do — fingerprint, face, PIN or screen lock — and the browser only offers the passkey to the site it was created for, so a fake sign-in page has nothing to collect.

In Authio a passkey is one of the sign-in steps a client can ask for. It can replace the password entirely or follow it as a second factor, and the tokens your app receives say which one happened.

How passkeys work in Authio

Passkeys are created and used on the hosted login, so they are bound to the domain it runs on and work for every client of the realm that offers the passkey step.
Registration asks for a discoverable credential and for user verification, so the person can sign in without typing a username. No attestation is requested: Authio does not ask the device to identify its maker.
Synced passkeys (iCloud Keychain, Google Password Manager, 1Password and others) and device-bound ones (Windows Hello, security keys) both work.
A device that already holds a passkey for the account cannot register a second one for it.
The account passes the same checks as a password sign-in: realm and client active, lockout, suspension, e-mail confirmation and address approval.

First step or second factor

Used as	What is checked	What the session records
The first step, instead of a password	The device must verify the person (biometrics or PIN). A passkey without verification is refused here.	Two factors: `swk` and `user`, with `acr` `3`.
A second factor, after the password	Verification is preferred, not required, so password managers that answer without it are accepted. Only the passkeys of the account whose password was accepted count.	`pwd` plus `swk`, and `user` when the device verified the person. `acr` is `3` with verification and `2` without.

A passkey sign-in still follows the client’s other steps: if the client also asks for the e-mail code, the code is asked after the passkey.

Turn passkeys on for a client

Add the passkey step
In Clients, open the client, choose Edit and go to Login layout. Add the passkey step: first in the list for a passwordless sign-in, after login for a second factor.
Choose its requirement and registration
The defaults, Preferred and Offer, build the base gradually: an account without a passkey signs in with its password and is offered to register one; from then on the passkey is asked every time. See requirement and registration for the other values.
Save
The step applies from the next sign-in. The account pages of the client start listing passkeys at the same time.

You want	Steps, in order	Policy
Password, with passkeys rolling out	`login`, `passkey`	Preferred and Offer.
Password plus a passkey for everyone	`login`, `passkey`	Required and Require.
Passkey first, password as the way in for newcomers	`passkey`, `login`	Preferred and Offer.
Passkey only	`passkey`	Required and Never: accounts register their passkey elsewhere first, for example on another client of the realm that has a `login` step.

Removing the passkey step closes the passkey endpoints for that client too, not only the button. On a passkey-only client, nobody can sign in until the step is back or another step is added.

Signing in with a passkey

What the person sees depends on where the step sits:

As the first step, the screen shows Continue with passkey. The browser lists the passkeys it holds for the site; no username is needed. If the client also has a login step, a link offers I don’t have a passkey yet — sign in with my password.
In the username field, when the client has both login and passkey, the browser’s autofill offers the saved passkeys next to saved passwords (WebAuthn conditional UI). Choosing one signs in without typing anything.
After the password, the browser asks for one of that account’s passkeys. A passkey of somebody else is refused as unknown.

A browser that cannot use passkeys says so on the screen and points to another way in.

Registering a passkey

There are two places a person registers a passkey:

During sign-in, when the step’s registration is Offer or Require: after signing in another way, the screen shows Set up a passkey, an optional field to name the device and Register this device. With Offer, Not now skips it. An account that already has a passkey elsewhere sees Passkey ready and can Also register this device.
From the account pages, on the Passkeys tab: name the device and choose Register this device. See Account self-service.

Encourage a second passkey. The account pages flag a passkey that lives on a single device, because losing that device means losing the credential.

When the passkey is not on this device

When the passkey is owed as a second factor, the screen offers My passkey is not on this device — send me a code instead. Authio sends a one-time code to the account’s e-mail and the code answers for the passkey step, even on a client whose steps include no e-mail code. A client that asks for a passkey therefore never locks out someone who lost their device.

The session records only what was actually used — pwd, otp and mfa, with acr 2 — so an app that needs the phishing-resistant level can tell it did not get it and ask again later.

A lost or retired device should also lose its passkey. The person removes it from the Passkeys tab of the account pages; an administrator removes it from the console (see below).

Managing passkeys

Where	Who	What it shows and does
Account pages, Passkeys tab	The person	Each passkey’s name, kind of device (this device, phone or tablet, USB, NFC or Bluetooth security key, smart card), whether it is synced, when it was added and last used. Register this device or remove a passkey. The tab lists passkeys only when the client offers the `passkey` step.
Users, the user’s Credentials tab	An administrator	The authenticator model identified by its AAGUID (Windows Hello, iCloud Keychain, YubiKey and others), transports, backup state and last use, with passkeys that would be lost with their device highlighted. Remove a passkey.

What your app receives

The ID token carries amr (the methods used) and acr (the level reached). Read them to decide whether a sign-in is strong enough for what the person is about to do:

Sign-in	`amr`	`acr`
Passkey alone, verified	`swk`, `user`, `mfa`	`3`
Password, then a verified passkey	`pwd`, `swk`, `user`, `mfa`	`3`
Password, then a passkey without verification	`pwd`, `swk`, `mfa`	`2`
Password, then the recovery code	`pwd`, `otp`, `mfa`	`2`

To ask for a phishing-resistant sign-in, send acr_values=3. It is best effort: see step-up.

Next steps

Multi-factorE-mail codes, push approval and step-up with acr_values.Hosted loginCompose the sign-in steps of a client and brand the screens.Account self-serviceThe pages where people manage their own passkeys and sessions.