Upgrade to 4.0Changelog
Reference

Responses and errors

Look up the success and error responses for each AuthEndpoints module: status codes, problem details, validation errors, and OAuth errors.

Most errors are problem details (application/problem+json). Validation errors are ValidationProblem responses: problem details with an errors object keyed by code. A few routes return other shapes. Each table below names the exact shape.

Shared responses

StatusBodyCause
400Plain text Invalid or missing CSRF token.The antiforgery filter rejected the request.
401 or 403EmptyThe route requires ReAuth and the request has no valid proof.
429EmptyA rate-limit policy rejected the request.

Identity management

RouteStatusShape
POST /register200Empty. Also returned for a duplicate email.
400ValidationProblem with Identity error codes, such as InvalidEmail or PasswordTooShort
GET /confirmEmail200Text Thank you for confirming your email.
401Empty
302Only when ConfirmEmailRedirectUri is set. Query status=confirmed or status=failed, and flow=confirm or flow=change-email.
POST /resendConfirmationEmail200Empty
POST /forgotPassword200Empty, always
POST /resetPassword200Empty
400ValidationProblem InvalidToken (bad code, unknown email, or unconfirmed email), or password-rule codes
GET /manage/2fa200{ "isTwoFactorEnabled", "recoveryCodesLeft" }
POST /manage/2fa200{ "sharedKey", "recoveryCodesLeft", "recoveryCodes", "isTwoFactorEnabled", "isMachineRemembered" }. sharedKey is empty unless the key was just created, it was reset, or the request turned 2FA on.
400ValidationProblem CannotResetSharedKeyAndEnable, RequiresTwoFactor, or InvalidTwoFactorCode
GET /manage/info, POST /manage/info200{ "email", "isEmailConfirmed" }
POST /manage/info400ValidationProblem OldPasswordRequired, InvalidEmail, PasswordMismatch, or password-rule codes
POST /manage/password200Empty. The account had no password, and newPassword was set.
400ValidationProblem UserAlreadyHasPassword, PasswordRequired, or password-rule codes
404Empty. Password sign-in is not mapped, or the signed-in user was not found.

ReAuth

RouteStatusShape
GET /manage/authMethods200{ "password", "authenticator", "recoveryCodes", "passkeys", "passkeyCount", "emailCode" }
POST /confirmIdentity/passkeyOptions200WebAuthn request options JSON
POST /confirmIdentity/emailCode/send200{ "expiresInSeconds", "resendAfterSeconds" }. Mapped when the email-code send module is registered (AddEmailCodeSendEndpoints or AddEmailCodeEndpoints). AddEmailCodeSignInEndpoints alone leaves it unmapped. Also returned when the send is suppressed.
400Problem details, title EmailCodeProofUnavailable. Step-up by email is off for this account.
401Empty. The caller is not signed in.
429Empty. AuthEndpoints.ConfirmIdentity.EmailCode rejected the request.
POST /confirmIdentity200{ "reauthToken" }. Cookie sign-in also sets AuthEndpoints.ReAuth. Authorization: Bearer does not. Confirm does not sign the user in.
400Plain JSON string Provide exactly one of Password, TwoFactorCode, TwoFactorRecoveryCode, CredentialJson, or EmailCode.
400Problem details, title EmailCodeProofUnavailable, when the only proof is emailCode and step-up by email is off for this account, or email-code send is not added.
401Empty. The proof was wrong, or the passkey belongs to another user.
RouteStatusShape
POST /login200Empty with a cookie. Identity bearer without query flags returns { "tokenType", "accessToken", "expiresIn", "refreshToken" }.
401Problem details, title RequiresTwoFactor, detail Two-factor authentication is required.
401Problem details, title Unauthorized, detail Invalid credentials.
POST /refresh (Identity bearer)200{ "tokenType", "accessToken", "expiresIn", "refreshToken" }
401Empty. The refresh token expired or the security stamp changed.
POST /logout200Empty
GET /csrfToken200{ "csrfToken" }

JWT

RouteStatusShape
POST /create200{ "accessToken", "tokenType": "Bearer" } and the AuthEndpoints.Jwt.RefreshToken cookie
400{ "error": "invalid_request", "error_description" }. Not problem details.
401Problem details, title Unauthorized, detail Invalid credentials. A wrong password, authenticator code, or recovery code.
401Problem details, title RequiresTwoFactor, detail Two-factor authentication is required., extension requiresTwoFactor: true
POST /refresh200{ "accessToken" } with a rotated refresh cookie
400{ "errors": ["..."] }. Messages: Missing refresh token cookie., Invalid refresh token. Token may be expired or revoked by the server., Associated user no longer exists.
GET /verify204Empty
POST /logout200Empty

Passkeys

RouteStatusShape
POST /passkeys/creationOptions, /requestOptions, /register/options200WebAuthn options JSON
POST /passkeys/register/options400ValidationProblem Email
POST /passkeys/register200{ "credentialId" } when sign-in is not allowed, and when cookie sign-in is allowed. Bearer sign-in returns AccessTokenResponse. JWT sign-in returns { "accessToken", "tokenType" }.
400Problem details, detail Unable to complete registration. A missing credential, a missing ceremony, a failed attestation, a taken email, and an existing user id share this body. The email is checked only after attestation succeeds.
400ValidationProblem Email
POST /passkeys/login200Cookie session: empty body and the application cookie. useSessionCookies=false makes that cookie persistent. useCookies is ignored. Identity bearer session: empty body and a cookie when useCookies or useSessionCookies is set, otherwise AccessTokenResponse. JWT session: { "accessToken", "tokenType" }.
400Problem details, title Invalid Credential
400ValidationProblem InvalidPasskeyState
401Problem details, title Unauthorized, detail Invalid credentials.
POST /passkeys/200{ "credentialId", "displayName", "createdAt" }
400ValidationProblem Name, UserMismatch, or InvalidPasskeyState. Problem details for a failed attestation or store error.
GET /passkeys/200{ "passkeys": [{ "credentialId", "displayName", "createdAt" }] }
PATCH /passkeys/200Empty
400ValidationProblem Name or InvalidCredentialId
404Empty
DELETE /passkeys/{credentialIdUrl}200Empty
400ValidationProblem InvalidCredentialId or LastSignInMethod
404Empty

Email code

RouteStatusShape
POST /emailCode/send200{ "expiresInSeconds", "resendAfterSeconds" }. Also returned when no mail is sent.
400ValidationProblem InvalidEmail
POST /emailCode/verify200Cookie session: empty body and the application cookie. Identity bearer session: token JSON when neither cookie query flag is set. JWT session: { "accessToken", "tokenType": "Bearer" }.
400ValidationProblem InvalidEmailCodeRequest, description Provide an email and a numeric code.
401Problem details, title Unauthorized, detail Invalid or expired code.
401Problem details, title RequiresTwoFactor, detail Two-factor authentication is required.

GET /emailCode/verify is 405.

External OAuth errors

The login and link callbacks redirect to ErrorPath?error=<code>&error_description=<text>. A request whose Accept header prefers application/json over text/html gets problem details instead, with title set to the code.

CodeStatusCause
provider_mismatch400The provider login does not match the callback route.
email_missing400The provider returned no email.
email_unverified400The provider email is not verified, and the flow requires it.
auto_link_disabled400A local account has this email, and AutoLinkByEmail is false.
email_unconfirmed400Auto-link was refused because the local email is not confirmed.
user_create_failed400Identity could not create the user.
login_link_failed400Identity could not add the login.
external_login_info_missing400No external login information was found for the callback.
user_locked_out401The user is locked out.
user_not_allowed401CanSignInAsync failed, for example because the email is not confirmed.

A provider error (error in the callback query) is passed through with status 400.

RouteStatusShape
GET /logins200[{ "loginProvider", "providerKey", "providerDisplayName" }]
DELETE /logins/{loginProvider}/{providerKey}204Empty
400Problem details, title last_signin_method
401Empty. Not signed in.
403Empty. Signed in, but no matching ReAuth proof.
404Empty