Upgrade to 4.0Changelog
Reference

Endpoint reference

Every route that AuthEndpoints maps, with its auth, CSRF, ReAuth, and rate-limit requirements.

Paths below use the password facade prefix /auth (PasswordAuthOptions.Path). Routes that MapPasswordAuth does not map use the same prefix, as a host that composes them on /auth would map them. External OAuth routes have no default prefix. The table uses /auth/external, the prefix from the examples.

AddPasswordAuth / MapPasswordAuth use one prefix (Path, default /auth) for register, login or POST /create, recovery, the session routes, confirm-email, and account management, including POST /manage/password. Passkeys share that prefix when Passkeys.ServerDomain is set. Email-code sign-in is not mapped. A host can add it, as in Email code. See Password auth.

Column meanings:

Identity management

Mapped by MapPasswordSignUpEndpoints, MapPasswordRecoveryEndpoints, MapConfirmEmailEndpoints, and MapAccountManagementEndpoints. MapPasswordAuth and MapIdentityManagementApi map all four. Management routes accept the application cookie, Identity bearer tokens, and JWT bearer tokens, when those schemes are registered.

MethodPathAuthCSRFReAuthRate limit
POST/auth/registerAccountAbuse
GET/auth/confirmEmail
POST/auth/resendConfirmationEmailYesYesAccountAbuse
POST/auth/forgotPasswordAccountAbuse
POST/auth/resetPasswordAccountAbuse
POST/auth/confirmIdentityYesYesConfirmIdentity
POST/auth/confirmIdentity/emailCode/send (only with email-code send)YesYesConfirmIdentity.EmailCode
POST/auth/confirmIdentity/passkeyOptionsYesYesConfirmIdentity
GET/auth/manage/authMethodsYes
GET/auth/manage/2faYes
POST/auth/manage/2faYesYesYes
GET/auth/manage/infoYes
POST/auth/manage/infoYesYesYes
POST/auth/manage/passwordYesYesYesAccountAbuse

POST /auth/confirmIdentity/emailCode/send exists only when email-code send is added: AddEmailCodeSendEndpoints or AddEmailCodeEndpoints. AddEmailCodeSignInEndpoints alone leaves it unmapped. MapAccountManagementEndpoints and MapReAuthEndpoints look for that send module. AddPasswordAuth adds none of them. POST /auth/confirmIdentity/passkeyOptions is mapped by MapAccountManagementEndpoints when passkey services are registered, which on the password facade means Passkeys.ServerDomain is set. MapIdentityManagementApi always maps it. POST /auth/manage/password returns 404 when password sign-in is not mapped. When POST /auth/manage/2fa changes the security stamp, it renews the ReAuth proof with its original expiry: a ReAuth cookie is reissued, and a token sent in X-AuthEndpoints-Reauth comes back renewed in the X-AuthEndpoints-Reauth response header. The other routes in this table do not renew the proof. Details: Identity management module.

Mapped by MapPasswordSignInEndpoints (POST /login) and MapCookieSessionEndpoints (POST /logout, GET /csrfToken). MapPasswordAuth maps both when Session is Cookie. MapCookieAuthEndpoints maps the same routes, with the LoginCookie handler on POST /login.

MethodPathAuthCSRFReAuthRate limit
POST/auth/loginLogin
POST/auth/logoutYesYes
GET/auth/csrfToken

Details: Cookie sign-in module.

Email code

Mapped by MapEmailCodeEndpoints, or by MapEmailCodeSendEndpoints and MapEmailCodeSignInEndpoints. The password facade does not map these routes. A password-facade host adds them with AddEmailCodeEndpoints and app.MapGroup("/auth").MapEmailCodeEndpoints<AppUser>(AuthEndpointsSession.Cookie). That also maps POST /auth/confirmIdentity/emailCode/send.

MethodPathAuthCSRFReAuthRate limit
POST/auth/emailCode/sendEmailCode.Send
POST/auth/emailCode/verifyLogin

Details: Email-code module.

Identity bearer sign-in

Mapped by MapBearerAuthEndpoints, which is POST /login plus MapBearerSessionEndpoints. The password facade does not map these routes. A host that also maps a cookie session puts these on a second prefix, such as /bearer, because both sessions map POST /logout.

MethodPathAuthCSRFReAuthRate limit
POST/auth/loginLogin
POST/auth/refresh
POST/auth/logoutYes

Details: Identity bearer sign-in module.

Passkeys

Mapped under {prefix}/passkeys by MapPasskeySignInEndpoints and MapPasskeyManagementEndpoints, or by MapPasskeyEndpoints, which maps both. MapPasswordAuth maps both when Passkeys.ServerDomain is set.

MethodPathAuthCSRFReAuthRate limit
POST/auth/passkeys/creationOptionsYesYesYesPasskey.ObtainOptions
POST/auth/passkeys/requestOptionsAmbient credentialPasskey.ObtainOptions
POST/auth/passkeys/register/optionsAmbient credentialPasskey.ObtainOptions
POST/auth/passkeys/registerAmbient credentialPasskey.Register
POST/auth/passkeys/loginAmbient credentialLogin
POST/auth/passkeys/YesYesYesPasskey.Register
GET/auth/passkeys/Yes
PATCH/auth/passkeys/YesYesYes
DELETE/auth/passkeys/{credentialIdUrl}YesYesYes

Signed-in routes accept the application cookie, Identity bearer, and JWT. A ReAuth credential alone does not. On the four anonymous ceremonies, the CSRF column means the antiforgery filter is attached for a cookie session and for JWT cookie refresh. Identity bearer and JWT body refresh omit it on those ceremonies. MapPasskeySignInEndpoints and MapPasskeySignUpEndpoints with no session argument keep it. The shared register-options route keeps it. Signed-in passkey changes always attach the filter. An Authorization: Bearer token that is not read from a cookie skips that check. See Antiforgery (CSRF) rules.

Details: Passkeys module.

JWT

Mapped by MapJwtPasswordEndpoints (POST /create) and MapJwtSessionEndpoints, or by MapJwtAuthEndpoints, which maps both. MapPasswordAuth maps both when Session is Jwt. The CSRF column is for cookie refresh transport. Body transport does not require antiforgery on refresh and logout, and it does not map GET /csrfToken.

MethodPathAuthCSRFReAuthRate limit
POST/auth/createLogin
POST/auth/refreshRefresh cookieYesLogin
GET/auth/verifyJWT bearer
POST/auth/logoutYes
GET/auth/csrfToken

Details: JWT module.

External OAuth

Mapped by MapExternalAuthEndpoints, MapExternalAuthProvider, and MapExternalAccountEndpoints. AddGitHub and AddGoogle only register the handlers. The password facade never maps these routes. {provider} is github or google. {scheme} is GitHub or Google.

MethodPathAuthCSRFReAuthRate limit
GET/auth/external/providers
GET/auth/external/login/{provider}Login
GET/auth/external/login/{provider}/callback
GET/auth/external/loginsYes
DELETE/auth/external/logins/{loginProvider}/{providerKey}YesYesYes
GET/auth/external/link/{scheme}YesLogin
GET/auth/external/link/{scheme}/callbackYes

The OAuth handlers also own /signin-github and /signin-google. Register those callback paths with each provider.

Details: External OAuth packages.

Active sessions

Mapped by MapActiveSessionEndpoints after AddActiveSessions. The password facade does not map these routes. The table uses /auth, the prefix from the examples. The CSRF column applies to cookie callers.

MethodPathAuthCSRFReAuthRate limit
GET/auth/sessionsYes
DELETE/auth/sessions/{id}YesYesYes
POST/auth/sessions/revokeOthersYesYesYes

Details: List and revoke signed-in sessions.

Building blocks

The tables above group the routes by module. The split Add* and Map* pairs are in the composition table. Call a smaller map when one prefix should omit register, login, or passkey management. Register the matching Add* method before the map. When that call is missing, the map throws InvalidOperationException. The message is Call {AddMethod} before {MapMethod}.

MapAddWhat it maps
MapPasswordEndpointsAddPasswordEndpointsPOST /register, POST /forgotPassword, POST /resetPassword, and POST /login for PasswordLoginMode.Cookie or PasswordLoginMode.IdentityBearer. PasswordLoginMode.None omits /login. Also maps confirm-email when that endpoint name is new. The default mode is Cookie.
MapCookieSessionEndpointsAddCookieSessionEndpointsPOST /logout, GET /csrfToken
MapBearerSessionEndpointsAddBearerSessionEndpointsPOST /refresh, POST /logout
MapJwtPasswordEndpointsAddJwtEndpointsPOST /create
MapJwtSessionEndpointsAddJwtEndpointsPOST /refresh, GET /verify, POST /logout, GET /csrfToken
MapPasskeySignInEndpointsAddPasskeySignInEndpoints (or AddPasskeyEndpoints)POST /passkeys/requestOptions, POST /passkeys/register/options, POST /passkeys/register, POST /passkeys/login. Maps confirm-email on the parent group when that name is new.
MapPasskeySignUpEndpointsAddPasskeySignUpEndpointsPOST /passkeys/register
MapPasskeyRegisterOptionsEndpointsAddPasskeyRegisterOptionsEndpointsPOST /passkeys/register/options
MapPasskeyManagementEndpointsAddPasskeyManagementEndpointsPOST /passkeys/creationOptions, POST /passkeys/, GET /passkeys/, PATCH /passkeys/, DELETE /passkeys/{credentialIdUrl}
MapConfirmEmailEndpointsAddAccountAbuseRateLimitingGET /confirmEmail, POST /resendConfirmationEmail. The exception text is Call AddAccountAbuseRateLimiting before MapConfirmEmailEndpoints.
MapAccountManagementEndpointsAddAccountManagementEndpointsPOST /confirmIdentity, GET /manage/authMethods, GET and POST /manage/2fa, GET and POST /manage/info, POST /manage/password. Maps confirm-email when that name is new. Maps POST /confirmIdentity/emailCode/send when AddEmailCodeSendEndpoints or AddEmailCodeEndpoints was called. AddEmailCodeSignInEndpoints alone leaves it unmapped. Maps POST /confirmIdentity/passkeyOptions when passkey services are registered. POST /manage/password returns 404 when password sign-in is not mapped.

These composites combine the maps above:

CompositePieces
MapIdentityManagementApiMapPasswordEndpoints with PasswordLoginMode.None, MapConfirmEmailEndpoints, and MapAccountManagementEndpoints. Passkey reauthentication options stay mapped.
MapCookieAuthEndpointsCookie POST /login plus MapCookieSessionEndpoints
MapBearerAuthEndpointsIdentity bearer POST /login plus MapBearerSessionEndpoints
MapJwtAuthEndpointsMapJwtPasswordEndpoints plus MapJwtSessionEndpoints
MapPasskeyEndpointsPasskey sign-in and management on one /passkeys group. This composite does not map confirm-email.

AddCookieAuthEndpoints registers password, cookie session, and account management. AddBearerAuthEndpoints registers password, bearer session, and account management. AddPasskeyEndpoints registers those password, cookie-session, and account-management modules in addition to passkey services. AddAuthEndpointsIdentity<TUser, TContext> registers Identity API endpoints, EF stores, default token providers, authorization, and antiforgery. RequireConfirmedAccount starts as true and Stores.SchemaVersion starts as version 3. The configure callback runs after those defaults. A later call applies its configure callback and can register roles. A later call that asks for a different role type throws.

Confirm-email is mapped once per name. The default is AuthEndpointsEndpointNames.ConfirmEmail<TUser>() (MapIdentityManagementApi-{TUser}-confirmEmail). A later map with the same name leaves the first route in place. MapConfirmEmailEndpoints returns a no-op builder in that case, and conventions on it do not reach the existing route. MapAccountManagementEndpoints and MapPasskeySignInEndpoints return a builder that includes the confirm-email group, so RequireCors and WithTags reach confirm and resend when this call mapped them. RequireAuthEndpointsUser() authorizes the application cookie, Identity bearer, and JWT bearer schemes that are registered. A ReAuth cookie or token is not a sign-in.

Two maps that add the same method and path log {FirstMap} and {SecondMap} both map {METHOD path}. on the AuthEndpoints category. These combinations stay quiet:

  • MapIdentityManagementApi and MapCookieAuthEndpoints on one prefix. Management uses PasswordLoginMode.None, so it does not map /login.
  • MapJwtPasswordEndpoints and MapJwtSessionEndpoints on one prefix. Their paths differ.
  • MapPasskeyEndpoints alone. It already includes sign-in and management.

These combinations log a duplicate:

  • MapPasswordEndpoints with the default cookie login mode and MapCookieAuthEndpoints on one prefix. Both map POST /login.
  • MapCookieSessionEndpoints and MapBearerSessionEndpoints on one prefix. Both map POST /logout. Use a different prefix for each session.
  • MapPasskeyEndpoints with MapPasskeySignInEndpoints or MapPasskeyManagementEndpoints on one prefix.

An email-code host that skips password routes is in Email-code only.