Passkeys module
Passkey (WebAuthn) endpoints for passwordless register/login and managing credentials on an existing account.
DI
builder.Services.AddPasskeyEndpoints<AppUser>();
This registers passkey rate limits/ReAuth and the default IdentityPasskeySignInCompleter<AppUser>. Prefer the generic overload for compose hosts so register/login can resolve IPasskeySignInCompleter<TUser>.
To choose the user id minted during passwordless register:
builder.Services.AddPasskeyUserIdFactory(() => Ulid.NewUlid().ToString());
Or register an IPasskeyUserIdFactory implementation. When no custom factory is registered, the id is Guid.NewGuid() (UUID v4).
On the password facade, passkeys stay off until Passkeys.ServerDomain is set.
Map
app.MapGroup("/auth").MapPasskeyEndpoints<AppUser>();
Routes are mapped under {prefix}/passkeys. The examples on this page use /auth, so the routes are under /auth/passkeys, as on the password facade.
Sign-in and credential management can be mapped on their own:
app.MapGroup("/auth").MapPasskeySignInEndpoints<AppUser>();
app.MapGroup("/auth").MapPasskeyManagementEndpoints<AppUser>();
To finish register and login with a built-in session, pass AuthEndpointsSession: MapPasskeySignInEndpoints<AppUser>(AuthEndpointsSession.Jwt). A single string is the confirm-email endpoint name, not a completer. When that string matches a registered completer name, the map logs a warning and still uses the default completer.
AddPasskeyEndpoints also registers the password, cookie-session, and account-management modules. A host that calls only AddPasskeyEndpoints, then MapIdentityManagementApi and MapCookieAuthEndpoints, does not fail the missing-Add* check for those maps. A missing Add* throws InvalidOperationException when the map runs. The message is Call {Add} before {Map}.
AddPasswordAuth with Passkeys.ServerDomain set registers the passkey sign-in, sign-up, register-options, and management modules, and the passkey module itself. It does not register the password module. A cookie session still registers the cookie-session module; a JWT session does not. An extra MapCookieAuthEndpoints or MapIdentityManagementApi throws the missing-Add* check on either session, because both maps require the password module.
AddPasskeyEndpoints registers every passkey module. AddPasskeySignInEndpoints, AddPasskeySignUpEndpoints, AddPasskeyRegisterOptionsEndpoints, and AddPasskeyManagementEndpoints register one each.
MapPasskeySignInEndpoints maps requestOptions, register/options, register, and login under /passkeys. POST /passkeys/register creates an account. The method also maps GET /confirmEmail and POST /resendConfirmationEmail on the parent group when that endpoint name is new.
Passkey login without that register route uses MapSignInEndpoints. Call AddPasskeySignInEndpoints and do not call AddPasskeyEndpoints or AddPasskeySignUpEndpoints. Those two register sign-up, and MapSignInEndpoints then maps POST /passkeys/register as well. MapPasskeySignInEndpoints always maps register, even when only AddPasskeySignInEndpoints was called.
MapPasskeyManagementEndpoints maps creationOptions, POST /, GET /, PATCH /, and DELETE /{credentialIdUrl} under /passkeys. MapPasskeyEndpoints maps sign-in and management on one /passkeys group and leaves confirm-email to the caller. Passwordless register can keep using AuthEndpointsEndpointNames.ConfirmEmail<TUser>(). Map MapConfirmEmailEndpoints or MapAccountManagementEndpoints with that name. The user store still has to support passkeys and email.
Routes
| Method | Path | Auth / extras |
|---|---|---|
POST | /passkeys/creationOptions | Signed-in + ReAuth + CSRF + rate limit |
POST | /passkeys/requestOptions | CSRF when the session has an ambient credential + rate limit; optional body { email } |
POST | /passkeys/register/options | CSRF when the session has an ambient credential; body { email }. The shared map always requires it. |
POST | /passkeys/register | CSRF when the session has an ambient credential; passwordless create + completer sign-in |
POST | /passkeys/login | CSRF when the session has an ambient credential; completer sign-in (useCookies / useSessionCookies for Identity completer) |
POST | /passkeys/ | Add passkey (signed-in + ReAuth + CSRF) |
GET | /passkeys/ | List passkeys (signed-in) |
PATCH | /passkeys/ | Rename (signed-in + ReAuth + CSRF). Name is trimmed, max 200. |
DELETE | /passkeys/{credentialIdUrl} | Remove (signed-in + ReAuth + CSRF). Refuses the last sign-in method. |
Anonymous ceremonies keep antiforgery for a cookie session and for JWT with cookie refresh transport. Identity bearer and JWT with body refresh transport omit it on those four routes. MapBearerAuthEndpoints maps no csrfToken route, and JWT body refresh maps none. MapPasskeyEndpoints, MapPasskeySignInEndpoints, and MapPasskeySignUpEndpoints with no session keep the token check. Pass AuthEndpointsSession.IdentityBearer to omit it on the anonymous ceremonies. The bearer facade does. MapPasskeyRegisterOptionsEndpoints is shared with cookie sessions and keeps the token check. Signed-in changes (creationOptions, POST /, PATCH /, DELETE) require antiforgery on every session. An Authorization: Bearer access token skips that check. Cookie callers, including useCookies=true, still send the token.
Identifier-first requestOptions with email may reveal passkey presence via allowCredentials. Omit email for usernameless/discoverable login.
Passwordless register flow
POST /auth/passkeys/register/optionswith{ "email": "..." }- Browser
navigator.credentials.create(...) POST /auth/passkeys/registerwith{ "email": "...", "credentialJson": "..." }
A successful user create sends the same confirmation email as password POST /register. The account is not marked confirmed. Completers still skip a session when CanSignInAsync fails (for example RequireConfirmedAccount). Duplicate-email and failed-attestation paths do not send that mail. Passwordless register never attaches a passkey to an existing user id; add a credential to an existing account with authenticated POST /passkeys/creationOptions then POST /passkeys/.
Client steps for passkey registration: Register users.
Sign-in completer
After a successful register/login ceremony, the library runs lockout and CanSignInAsync. It calls IPasskeySignInCompleter<TUser> only when sign-in is allowed.
Default: Identity
IdentityPasskeySignInCompleter honors the same query flags as Identity bearer Login (MapBearerAuthEndpoints):
?useCookies=true→ persistent application cookie?useSessionCookies=true→ session application cookie- neither → Identity bearer token (
AccessTokenResponse)
Login flags, not cookie password login. ?useCookies=true has no effect on cookie POST /login, with LoginCookie or the Cookie completer. The password facade passes its session to MapPasskeySignInEndpoints, so it does not use this default. See Cookie auth.Passwordless register returns one body:
- Cookie sign-in (
useCookiesoruseSessionCookies) returnsPasskeyCredentialResponse(credentialId;displayNameandcreatedAtwhen present) and sets the application cookie. - Bearer sign-in returns
AccessTokenResponse.SignInAsyncalready wrote that body, so the response does not also includecredentialId. - When sign-in is not allowed, register returns that credential id and does not issue a session or tokens.
Login returns 401 Invalid credentials when sign-in is not allowed. A custom completer cannot issue a cookie or token on those paths.
List and add return the same shape. POST /passkeys/ and PATCH /passkeys/ accept a name (trimmed, max 200). Identity stores that as UserPasskeyInfo.Name. JSON still uses displayName. A rename longer than 200 characters returns a validation problem Name.
When the library gate denies sign-in (unconfirmed account, lockout):
| Kind | Response |
|---|---|
| Register | PasskeyCredentialResponse (credential id); no session or tokens |
| Login | 401 Invalid credentials |
Simple JWT
Pass AuthEndpointsSession.Jwt to MapPasskeySignInEndpoints. That session needs AddJwtEndpoints:
builder.Services.AddPasskeyEndpoints<AppUser>();
builder.Services.AddJwtEndpoints<AppUser, AppDbContext>(o =>
{
o.Issuer = "https://example.com";
o.Audience = "https://example.com";
o.SigningOptions.SymmetricKey = builder.Configuration["Jwt:SymmetricKey"];
});
app.MapGroup("/auth").MapPasskeySignInEndpoints<AppUser>(AuthEndpointsSession.Jwt);
Successful passkey register and login return the same shape as JWT /create: access token in JSON and the HttpOnly refresh cookie. The body does not include credentialId. Cookie query flags are ignored.
JWT body transport
With refresh transport set to Body (SimpleJwtOptions.RefreshTokenTransport or JwtSessionOptions.RefreshTokenTransport), MapJwtSessionEndpoints does not map GET /csrfToken. Anonymous passkey ceremonies mapped for that JWT session (requestOptions, register/options, register, login) do not require an antiforgery token. Signed-in passkey changes still do. A password facade with Session set to Jwt and body transport is that session. Cookie refresh transport still requires the token from GET /csrfToken on the anonymous ceremonies.
AddPasskeySignInCompleter and JwtPasskeySignInCompleter<TUser> are obsolete. They still run when the map passes no session. See Upgrade to 4.0.
Signed-in routes accept the application cookie, Identity bearer, and JWT bearer schemes that the host registered (the same set as account management). A ReAuth cookie or X-AuthEndpoints-Reauth token is not a sign-in. GET /passkeys/ returns 401 until one of those sign-in schemes authenticates. Mutations also require ReAuth for that same user, so a signed-in caller without a matching step-up proof gets 403.
Signed-in changes run the usual skip rule. A cookie session must send a CSRF token. An Authorization: Bearer access token skips the check. A token the host reads from a cookie, with no Authorization header, still needs a CSRF token.
Constraints
- Passwordless register needs
IdentityUserwithstringorGuidkey. The default user id isGuid.NewGuid()(UUID v4). Apps can override the minted id by registeringIPasskeyUserIdFactory. MapPasskeyEndpointsthrows at map time if the user store lacks passkey or email support. The module is email-keyed.- Anonymous ceremonies (
requestOptions,register/options,register,login) require CSRF for a cookie session and for JWT with cookie refresh transport. Identity bearer and JWT with body refresh transport do not.MapPasskeySignInEndpointsandMapPasskeySignUpEndpointswith no session argument keep the check.MapBearerAuthEndpointsmaps no token route. The Identity ceremony state lives in theTwoFactorUserIdSchemecookie (Identity.TwoFactorUserId). That cookie is single-use state, not a credential, and clients must send it between the options call and the verify call.registerandlogincan also set an application cookie whenuseCookiesoruseSessionCookiesis true. DELETE /passkeys/{credentialIdUrl}returns a validation problemLastSignInMethodwhen the passkey is the only sign-in method (no password and no external login). Two-factor authentication does not count.- Sensitive credential mutations require ReAuth.