Upgrade to 4.0Changelog
Guides

Add, rename, and remove passkeys

Let a signed-in user add a passkey to their account, list passkeys, rename them, and remove them.

A signed-in user manages passkeys under /auth/passkeys when the password facade has Passkeys.ServerDomain set. Adding, renaming, and removing a passkey, and requesting creation options, require a fresh ReAuth proof for that same user. The caller must already be signed in. A ReAuth cookie or X-AuthEndpoints-Reauth token by itself is not a sign-in. Those requests return 401. Stamp checks and the 403 are in ReAuth.

CSRF depends on how that sign-in was presented:

Sign-inCSRF on add, rename, remove, and creation options
Application cookieRequired. Send RequestVerificationToken.
Identity bearer or JWT in Authorization: BearerSkipped.
Access token stored in a cookie and read in OnMessageReceived, with no Authorization headerRequired. Hosts that keep the token in a cookie send the CSRF token.

The sample below is the cookie stack. Send credentials: 'include' on every cookie request. Add, rename, remove, and creation options always attach the antiforgery filter. An Authorization: Bearer access token skips it. Cookie callers, including useCookies=true, still send the token. To create a new account with a passkey, see Register users. Anonymous passkey register and login require a CSRF token for a cookie session and for JWT cookie refresh. Identity bearer and JWT body refresh do not. See Passkeys module.

TaskEndpointReAuthCSRF
Get creation optionsPOST /auth/passkeys/creationOptionsYesCookie session, or a token read from a cookie
Add a passkeyPOST /auth/passkeys/YesCookie session, or a token read from a cookie
List passkeysGET /auth/passkeys/NoNo
Rename a passkeyPATCH /auth/passkeys/YesCookie session, or a token read from a cookie
Remove a passkeyDELETE /auth/passkeys/{credentialIdUrl}YesCookie session, or a token read from a cookie

Add a passkey

  1. Complete step-up. See Require step-up before sensitive actions.
  2. Get creation options from POST /auth/passkeys/creationOptions. The options are for the signed-in user.
  3. Call navigator.credentials.create.
  4. Send POST /auth/passkeys/ with { "credentialJson", "name"? }. AuthEndpoints trims name. A name longer than 200 characters returns a 400 validation problem with the key Name.
    const headers = { 'Content-Type': 'application/json', 'RequestVerificationToken': csrfToken };
    
    const options = await fetch('/auth/passkeys/creationOptions', {
      method: 'POST', credentials: 'include', headers
    }).then(r => r.json());
    
    const credential = await navigator.credentials.create({
      publicKey: PublicKeyCredential.parseCreationOptionsFromJSON(options)
    });
    
    const added = await fetch('/auth/passkeys/', {
      method: 'POST', credentials: 'include', headers,
      body: JSON.stringify({ credentialJson: JSON.stringify(credential), name: 'Work laptop' })
    }).then(r => r.json()); // { credentialId, displayName, createdAt }
    
  5. Check the response:
    • 200 { "credentialId", "displayName", "createdAt" }: the passkey is stored.
    • 400 validation problem UserMismatch: the passkey belongs to a different user.
    • 400 validation problem InvalidPasskeyState: no ceremony was underway. Start again from step 2.
    • 400 with a detail that starts with "Could not add the passkey": the attestation failed.

List passkeys

Send GET /auth/passkeys/. The response is { "passkeys": [{ "credentialId", "displayName", "createdAt" }] }. credentialId is Base64Url.

Rename a passkey

Complete step-up, then send PATCH /auth/passkeys/ with { "id": "<credentialId>", "newName": "..." }. AuthEndpoints trims newName. A name longer than 200 characters returns a 400 validation problem with the key Name, and the stored name stays as it was. A value that is only whitespace clears the name. The success response is 200 with an empty body. An unknown id returns 404. An id that is not valid Base64Url returns a 400 validation problem InvalidCredentialId.

Remove a passkey

Complete step-up, then send DELETE /auth/passkeys/<credentialId>. The response is 200 with an empty body. An unknown id returns 404. An id that is not valid Base64Url returns a 400 validation problem InvalidCredentialId.

The delete is refused when this passkey is the user's only sign-in method: the account has no password and no external login, and this is the only passkey. The response is a 400 validation problem with the key LastSignInMethod and the detail Cannot remove the last sign-in method. Two-factor authentication is not a sign-in method. An account with a password, an external login, or another passkey can delete this one.