Require step-up before sensitive actions
A sensitive change needs a fresh ReAuth proof on top of a sign-in. The proof is the AuthEndpoints.ReAuth cookie, the reauthToken, or both. Neither one signs the user in. A request that sends only that cookie or the X-AuthEndpoints-Reauth header is 401.
Cookie sign-in receives the cookie and reauthToken. A caller signed in with Authorization: Bearer receives reauthToken only. Send that token in X-AuthEndpoints-Reauth. Lifetime, stamp checks, and the schemes are in the ReAuth module.
These actions require ReAuth:
POST /auth/manage/2fa,POST /auth/manage/info, andPOST /auth/manage/password.- Passkey
creationOptions, add, rename, and delete. - External OAuth unlink.
- Host endpoints that call
.RequireReauth().
The steps assume a signed-in cookie session on the password facade. Both POST /auth/confirmIdentity and POST /auth/confirmIdentity/passkeyOptions require a CSRF token, because management maps them with antiforgery. Get the token from GET /auth/csrfToken and send it in the RequestVerificationToken header. A missing token returns 400 with the body Invalid or missing CSRF token.
Complete step-up
- Call the protected action, for example
POST /auth/manage/info. A signed-in user without a matching ReAuth proof gets403. A caller who is not signed in gets401. - Send
GET /auth/manage/authMethodsto see which proofs the user has. The response is{ "password", "authenticator", "recoveryCodes", "passkeys", "passkeyCount", "emailCode" }. - Collect exactly one proof:
{ "password": "..." }{ "twoFactorCode": "..." }{ "twoFactorRecoveryCode": "..." }{ "credentialJson": "..." }from a passkey. See Use a passkey as the proof.{ "emailCode": "..." }afterPOST /auth/confirmIdentity/emailCode/send. See Use an emailed code as the proof.
- Send the proof to
POST /auth/confirmIdentitywith the CSRF header. - Check the response:
200 { "reauthToken" }. A cookie sign-in also setsAuthEndpoints.ReAuth. AnAuthorization: Bearersign-in does not. Confirm does not sign the user in.400"Provide exactly one of Password, TwoFactorCode, TwoFactorRecoveryCode, CredentialJson, or EmailCode.": the body had zero proofs or more than one.400with titleEmailCodeProofUnavailable: the only proof wasemailCode, and that proof is off for this account.401: the proof was wrong.
- Retry the protected action. A browser sends the ReAuth cookie automatically. An API client adds the
X-AuthEndpoints-Reauth: <reauthToken>header. A signed-in caller whose security stamp changed after confirm gets403. AfterPOST /auth/manage/2fachanges the stamp, the200response carries a renewed token in theX-AuthEndpoints-Reauthresponse header. Use that token from then on. The token keeps the original expiry. A password change onPOST /auth/manage/info,POST /auth/manage/password, and external unlink do not renew the proof. Complete step-up again after them. Details are in ReAuth.
Use a passkey as the proof
- Send
POST /auth/confirmIdentity/passkeyOptionswith the CSRF header. The options are for the signed-in user. - Call
navigator.credentials.get. - Send the credential to
POST /auth/confirmIdentity.
const headers = { 'Content-Type': 'application/json', 'RequestVerificationToken': csrfToken };
const options = await fetch('/auth/confirmIdentity/passkeyOptions', {
method: 'POST', credentials: 'include', headers
}).then(r => r.json());
const credential = await navigator.credentials.get({
publicKey: PublicKeyCredential.parseRequestOptionsFromJSON(options)
});
await fetch('/auth/confirmIdentity', {
method: 'POST', credentials: 'include', headers,
body: JSON.stringify({ credentialJson: JSON.stringify(credential) })
});
A passkey that belongs to a different user returns 401.
Native and mobile clients
Call POST /auth/confirmIdentity with Authorization: Bearer and exactly one proof. Keep reauthToken in memory only, then send it on the sensitive call. Do not store it in durable storage, and do not expect a ReAuth cookie.
const confirm = await fetch('/auth/confirmIdentity', {
method: 'POST',
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ password })
});
const { reauthToken } = await confirm.json();
await fetch('/auth/manage/info', {
method: 'POST',
headers: {
Authorization: `Bearer ${accessToken}`,
'X-AuthEndpoints-Reauth': reauthToken,
'Content-Type': 'application/json'
},
body: JSON.stringify({ oldPassword, newPassword })
});
Changing the password, resetting it, or calling UpdateSecurityStampAsync cancels that in-memory token. Confirm again before the next sensitive call.
Use an emailed code as the proof
emailCode is true only when the email-code send module is registered (AddEmailCodeSendEndpoints or AddEmailCodeEndpoints), EmailCode.ReAuth.Enabled is true (the default), the account email is confirmed, and the user has no password, no authenticator, and no passkey. AddEmailCodeSignInEndpoints alone leaves it false. Who can use the proof, the code lifetime, and lockout are in the ReAuth module.
- Send
POST /auth/confirmIdentity/emailCode/sendwith no body and the CSRF header. - Send
{ "emailCode" }toPOST /auth/confirmIdentity.
A successful confirm returns reauthToken and, for a cookie sign-in, sets AuthEndpoints.ReAuth. It does not create a new sign-in.
Protect your own endpoint
Call .RequireReauth() together with .RequireAuthorization() that signs the user in. AddPasswordAuth registers the ReAuth schemes. A composed host calls AddAccountManagementEndpoints, or AddCookieAuthEndpoints or AddBearerAuthEndpoints, which call it. The policy name stays ReAuthPolicy, and that policy adds no authentication schemes. It does not sign the user in, and it does not replace HttpContext.User.
app.MapPost("/billing/update", handler)
.RequireAuthorization()
.RequireReauth();
.RequireAuthorization() without schemes uses the host's default sign-in. With AddIdentityApiEndpoints, that is the application cookie or the Identity bearer token. Pass the JWT scheme as well when that endpoint should accept a JWT. A signed-in caller without a matching proof gets 403. A route that calls .RequireReauth() without a sign-in authorization fails.