Add, rename, and remove passkeys
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-in | CSRF on add, rename, remove, and creation options |
|---|---|
| Application cookie | Required. Send RequestVerificationToken. |
Identity bearer or JWT in Authorization: Bearer | Skipped. |
Access token stored in a cookie and read in OnMessageReceived, with no Authorization header | Required. 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.
| Task | Endpoint | ReAuth | CSRF |
|---|---|---|---|
| Get creation options | POST /auth/passkeys/creationOptions | Yes | Cookie session, or a token read from a cookie |
| Add a passkey | POST /auth/passkeys/ | Yes | Cookie session, or a token read from a cookie |
| List passkeys | GET /auth/passkeys/ | No | No |
| Rename a passkey | PATCH /auth/passkeys/ | Yes | Cookie session, or a token read from a cookie |
| Remove a passkey | DELETE /auth/passkeys/{credentialIdUrl} | Yes | Cookie session, or a token read from a cookie |
Add a passkey
- Complete step-up. See Require step-up before sensitive actions.
- Get creation options from
POST /auth/passkeys/creationOptions. The options are for the signed-in user. - Call
navigator.credentials.create. - Send
POST /auth/passkeys/with{ "credentialJson", "name"? }. AuthEndpoints trimsname. A name longer than 200 characters returns a400validation problem with the keyName.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 } - Check the response:
200 { "credentialId", "displayName", "createdAt" }: the passkey is stored.400validation problemUserMismatch: the passkey belongs to a different user.400validation problemInvalidPasskeyState: no ceremony was underway. Start again from step 2.400with 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.