Upgrade to 4.0Changelog
Concepts

AuthEndpoints vs MapIdentityApi and others

How AuthEndpoints differs from wiring Identity yourself, from OpenIddict, and from MapIdentityApi.

AuthEndpoints is a first-party auth API on top of ASP.NET Core Identity. Use it when you own the users. Use something else when you need an OAuth or OpenID Connect server, or when Microsoft's Identity API endpoints already cover the whole job.

vs wiring Identity yourself

You still use Identity, EF Core, and your user type. AuthEndpoints maps the endpoints you would otherwise write: register, login, 2FA, password reset, passkeys, and GitHub or Google sign-in. You also get the hardening that hand-written endpoints often miss: rate limits, CSRF checks, and generic responses that do not reveal which emails exist.

vs OpenIddict

OpenIddict is an OAuth 2 and OpenID Connect server. Use it when other apps sign in to you as a provider. AuthEndpoints is for your own web and mobile clients that call your own API. It issues first-party cookies or tokens. It is not a federation server.

vs Identity API endpoints (MapIdentityApi)

Identity API endpoints give you a bearer-token first-party API. AuthEndpoints covers that job and the cookie-app job. It adds passkeys, step-up ReAuth, composable modules, and hardening defaults: rate limits, antiforgery, lockout, and refresh-token reuse detection. Use MapIdentityApi if the framework sample is enough. Use AuthEndpoints if you need cookies, passkeys, or to compose only the routes you need.

The next sections list where MapIdentityApi stops. Shared routes side by side compares register, login, password reset, and two-factor authentication route by route.

What MapIdentityApi maps

MapIdentityApi<TUser>() is ASP.NET Core's Identity API. One call maps register, login, refresh, email confirmation, password reset, and account management onto your Identity user store. AuthEndpoints uses that same store. The sections below list where MapIdentityApi stops in .NET 10, and which AuthEndpoints call covers each gap.

In .NET 10, MapIdentityApi<TUser>() maps this set. Paths sit at the app root unless you wrap the call in MapGroup.

MethodPath
POST/register
POST/login
POST/refresh
GET/confirmEmail
POST/resendConfirmationEmail
POST/forgotPassword
POST/resetPassword
POST/manage/2fa
GET/manage/info
POST/manage/info
builder.Services
    .AddIdentityApiEndpoints<AppUser>()
    .AddEntityFrameworkStores<AppDbContext>();

app.MapGroup("/identity").MapIdentityApi<AppUser>();

POST /login uses the Identity bearer scheme unless the query string sets useCookies or useSessionCookies, which issue the application cookie instead. Request bodies are the Identity types (RegisterRequest, LoginRequest, and the rest). There is no GET /manage/2fa. The method's documentation comment mentions logging out. The method does not map a logout route.

Logout

MapIdentityApi has no logout route. The Identity API authorization article tells you to add your own POST /logout that calls SignInManager.SignOutAsync(). That signs out the application scheme, plus the external and two-factor user-id schemes when they are registered. It does not sign out the two-factor remember-client cookie. It does not revoke bearer tokens. The bearer handler treats sign-out as a no-op, so the access token and the refresh token stay valid until they expire.

AuthEndpoints maps a logout route on each sign-in stack. Each stack ends a different thing. Client steps: Sign users out.

StackRouteWhat logout ends
Cookie (password facade default)POST /auth/logoutApplication, external, two-factor user-id, remember-client, and ReAuth cookies. Requires a signed-in user and a CSRF token.
Identity bearerPOST /auth/logoutThose same cookies. Bearer access and refresh tokens stay valid until they expire. Requires a signed-in user. No CSRF token.
JWTPOST /auth/logoutThe refresh-token family for the refresh cookie, and the cookie itself. The access JWT stays valid until it expires (15 minutes by default). CSRF token required. A signed-in user is not required.

Cookie logout:

const { csrfToken } = await fetch('/auth/csrfToken', { credentials: 'include' }).then(r => r.json());
await fetch('/auth/logout', {
  method: 'POST',
  credentials: 'include',
  headers: { 'RequestVerificationToken': csrfToken }
});

GET /auth/csrfToken is part of the cookie session module. MapIdentityApi does not map it.

Choose which endpoints to map

MapIdentityApi maps the full table above in one call. MapGroup("/identity") prefixes every route with /identity. The builder it returns can add conventions to that group. It has no parameter that omits /register, and no parameter that renames /login.

AuthEndpoints splits the same jobs into modules. Map the ones you need:

ModuleWhat it adds
MapIdentityManagementApiRegister, confirm email, resend, forgot/reset password, manage info, set password, 2FA, ReAuth
MapPasswordEndpointsRegister, forgot/reset password, and login for cookie or Identity bearer. PasswordLoginMode.None omits login.
MapConfirmEmailEndpointsGET /confirmEmail and POST /resendConfirmationEmail, once per endpoint name
MapAccountManagementEndpointsManage info, set password, 2FA, auth methods, and POST /confirmIdentity
MapCookieAuthEndpointsCookie POST /login, POST /logout, GET /csrfToken
MapCookieSessionEndpointsCookie POST /logout and GET /csrfToken
MapBearerAuthEndpointsIdentity bearer POST /login, POST /refresh, POST /logout
MapBearerSessionEndpointsIdentity bearer POST /refresh and POST /logout
MapJwtAuthEndpointsJWT POST /create, POST /refresh, GET /verify, POST /logout, GET /csrfToken
MapJwtPasswordEndpointsJWT POST /create
MapJwtSessionEndpointsJWT refresh, verify, logout, and CSRF token
MapPasskeyEndpointsPasskey register, login, and credential management
MapPasskeySignInEndpointsPasskey register and login, plus confirm-email on the parent group when that name is new
MapPasskeyManagementEndpointsSigned-in passkey list, add, rename, and delete

MapPasswordAuth is one composition: password sign-up, sign-in, recovery, confirm-email, account management, and one session under Path (default /auth). Passkeys stay off until Passkeys.ServerDomain is set.

This maps that composition with a cookie session under /api/auth:

builder.Services.AddPasswordAuth<AppUser, AppDbContext>(o =>
{
    o.Path = "/api/auth";
});
builder.Services.AddTransient<IEmailSender<AppUser>, MyEmailSender>();

var app = builder.Build();
app.UseAuthEndpoints();
app.MapPasswordAuth<AppUser>();

POST /api/auth/login on that host is cookie login. The relative names stay /login, /register, and /logout. AuthEndpoints does not rename those segments. MapPasswordAuth and MapIdentityManagementApi always include /register. MapCookieAuthEndpoints always includes /login. The smaller maps omit a piece: MapPasswordEndpoints with PasswordLoginMode.None skips /login, and MapCookieSessionEndpoints maps logout and the CSRF token. An email-code host uses those pieces. See Email-code only.

To skip cookie login and map JWT instead, compose the modules. Register the matching services first, call modelBuilder.UseRefreshToken() on the DbContext, and migrate. The route map is:

var auth = app.MapGroup("/auth");
auth.MapIdentityManagementApi<AppUser>();
auth.MapJwtAuthEndpoints<AppUser>();

Full host setup: Build a custom auth stack. Prefix reference: Configuration options.

JWT, opaque bearer tokens, and cookies

MapIdentityApi login without useCookies or useSessionCookies returns Identity bearer tokens (accessToken, refreshToken, expiresIn, tokenType). Those values are data-protection tickets (BearerTokenProtector and RefreshTokenProtector), not JWTs. Microsoft's Identity API article states that the tokens are not standard JSON Web Tokens. Another service validates them with the Identity bearer handler and the same data-protection keys. JwtBearer and a signing key do not validate them. ?useCookies=true or ?useSessionCookies=true on that same /login issues the application cookie and does not return a token body.

AuthEndpoints has three password sign-in stacks. Identity bearer is the same ticket format as MapIdentityApi. JWT is a separate opt-in.

StackWhat login returnsRefresh
Cookie (password facade default)Application cookie. Empty body.The browser sends the cookie.
Identity bearerOpaque accessToken and refreshToken in the bodyPOST /auth/refresh with { "refreshToken" }
JWTJWT accessToken in the body, refresh token in the AuthEndpoints.Jwt.RefreshToken cookiePOST /auth/refresh with that cookie and a CSRF token. The stored token is a hash. Each refresh rotates it. Reuse of an old token revokes the family.

With a cookie session on the password facade, POST /auth/login always uses the application cookie. useCookies is ignored there. A persistent cookie is ?useSessionCookies=false. The flag table for Identity bearer login matches MapIdentityApi. Details: Choose your sign-in setup and Shared routes side by side.

For a JWT session, set Session to Jwt and pass Jwt. You still call modelBuilder.UseRefreshToken() and add a migration:

builder.Services.AddPasswordAuth<AppUser, AppDbContext>(o =>
{
    o.Session = AuthEndpointsSession.Jwt;
    o.Jwt = jwt =>
    {
        jwt.Issuer = "https://example.com";
        jwt.Audience = "https://example.com";
        jwt.SigningOptions.SymmetricKey = builder.Configuration["Jwt:SymmetricKey"];
    };
});

MapPasswordAuth then maps /auth/create, /auth/refresh, /auth/verify, /auth/logout, and /auth/csrfToken instead of cookie /auth/login. The password facade maps one session. A host with cookie and JWT sessions side by side composes them on different prefixes. See Build a custom auth stack. Signing keys, algorithms, and lifetimes: JWT module.

Passkeys

MapIdentityApi does not map passkey routes. The .NET 10 Blazor Identity template has passkey pages, and its MapAdditionalIdentityEndpoints posts to /Account/PasskeyCreationOptions and /Account/PasskeyRequestOptions. Those routes belong to that template. They are not MapIdentityApi, and they are not a passkey register, login, and credential API for a separate client.

AuthEndpoints maps that API. The password facade maps passkeys only when Passkeys.ServerDomain is set, under /auth/passkeys. See Choose your sign-in setup.

builder.Services.AddPasswordAuth<AppUser, AppDbContext>(o =>
{
    o.Passkeys.ServerDomain = "example.com";
});

Mapped routes include POST /auth/passkeys/register, POST /auth/passkeys/login, GET /auth/passkeys/, and add, rename, and delete. Passkey sign-in skips two-factor authentication. The password facade finishes passkey sign-in in its own session, so a cookie session sets the application cookie. A composed MapPasskeySignInEndpoints with no session argument follows Identity bearer query flags (useCookies or useSessionCookies) instead. Pass AuthEndpointsSession.Jwt when passkey sign-in should issue a JWT. Route table and ceremony: Passkeys module. Client steps: Register users and Sign users in.

When MapIdentityApi is enough

Use MapIdentityApi when its ten routes, and a logout handler you write, cover the app. Use AuthEndpoints when you need a logout route, a prefix with only some modules, a JWT access token, or passkey endpoints.

Shared routes side by side

Both stacks sit on ASP.NET Core Identity and your EF user store. Stock here means Microsoft's Identity API endpoints (AddIdentityApiEndpoints and MapIdentityApi) or the same routes written by hand. AuthEndpoints in the tables means the password facade: AddPasswordAuth, UseAuthEndpoints, and MapPasswordAuth with the default cookie session. It leaves passkeys off until Passkeys.ServerDomain is set.

This section compares the routes that both stacks share.

Request bodies stay Identity-shaped (RegisterRequest, LoginRequest, ForgotPasswordRequest, ResetPasswordRequest, TwoFactorRequest). AuthEndpoints maps the routes and adds cookie login, CSRF where required, rate limits, and ReAuth. It does not invent alternate DTOs.

AuthEndpoints tables use the password facade default prefix /auth (Path). Stock MapIdentityApi has no built-in prefix unless the host wraps it in MapGroup.

AuthEndpoints-only on this surface: GET /auth/csrfToken, cookie POST /auth/logout, and ReAuth (/manage/authMethods, /confirmIdentity). Stock MapIdentityApi does not map logout.

Client steps for these flows are in Guides.

Host setup

Stock (MapIdentityApi)

builder.Services
    .AddIdentityApiEndpoints<AppUser>()
    .AddEntityFrameworkStores<AppDbContext>();

var app = builder.Build();

// Optional prefix — without MapGroup, routes are at the app root (/register, /login, …).
app.MapGroup("/identity").MapIdentityApi<AppUser>();

You still wire authentication, authorization, antiforgery, CORS, and rate limiting yourself. Login is bearer-first unless the client passes cookie query flags.

AuthEndpoints (password facade)

builder.Services.AddPasswordAuth<AppUser, AppDbContext>();
builder.Services.AddTransient<IEmailSender<AppUser>, MyEmailSender>();

var app = builder.Build();

app.UseAuthEndpoints(); // authentication, authorization, rate limiting, antiforgery
app.MapPasswordAuth<AppUser>();

The session is a cookie. Passkeys stay off. See Quick start.

CSRF on the AuthEndpoints cookie stack applies to cookie logout, manage POSTs, ReAuth, authenticated resendConfirmationEmail, and every passkey route except the list. It does not apply to register, login, forgotPassword, or resetPassword. See Antiforgery (CSRF) rules.

Register

Stock Identity APIAuthEndpoints password facade
RoutePOST /register (or POST /identity/register with MapGroup)POST /auth/register
BodyIdentity register (email, password)Same Identity body
CSRFHost policy (endpoint does not require antiforgery by default)Not required (RequireAntiforgery is not on register)
Duplicate email200 (no enumeration)200 (no enumeration)
Confirmed-account policyHost Identity optionsRequireConfirmedAccount default true
After 200Not signed inNot signed in (200 ≠ session)
ConfirmGET …/confirmEmail?userId&codeGET /auth/confirmEmail?userId&code, then login. Optional ConfirmEmailRedirectUri → 302 with status / flow
Rate limitHost-ownedBuilt-in account rate limits

Client flow: register → check email → confirm → login. Steps: Register users.

Login

Stock Identity APIAuthEndpoints password facade
RoutePOST /login (or under your MapGroup)POST /auth/login
HandlerIdentity LoginShared password pipeline, finished by the Cookie completer
BodyIdentity LoginRequestSame (email, password, optional 2FA fields)
Default successIdentity bearer tokens (AccessTokenResponse)Application cookie only (no bearer): empty body + Set-Cookie (TypedResults.Empty). Session when the flag is omitted
Cookie query flagsuseCookies / useSessionCookies select cookie vs bearerOnly useSessionCookies (useCookies ignored). Persistent: ?useSessionCookies=false
CSRF on loginNot requiredNot required
LogoutNot in MapIdentityApiPOST /auth/logout (auth + CSRF)
CSRF helperHost-ownedGET /auth/csrfToken for logout, manage, ReAuth, resend
LockoutIdentity lockoutLockout + login rate limit

Full flag tables: Cookie auth. Bearer-style Identity login is available by composing MapBearerAuthEndpoints. The password facade does not map it.

Password reset

Stock Identity APIAuthEndpoints password facade
ForgotPOST …/forgotPassword { email } → always 200POST /auth/forgotPassword → always 200
CSRF / session on forgotNot requiredNot required
MailYour IEmailSender<TUser>Same (Production rejects Identity's no-op sender)
Reset codeFrom mailBase64Url token from the sender; send that value as resetCode
ResetPOST …/resetPassword { email, resetCode, newPassword }Same Identity body on /auth/resetPassword
CSRF / session on resetNot requiredNot required
ThenPOST …/loginPOST /auth/login

Client steps: Reset a forgotten password.

Two-factor authentication

Stock Identity APIAuthEndpoints password facade
StatusNo GET — use POST /identity/manage/2fa (response includes sharedKey / flags)GET /auth/manage/2fa → isTwoFactorEnabled and recoveryCodesLeft
Shared keyOn stock POST response (TwoFactorResponse.sharedKey)Mint/read via POST /auth/manage/2fa + {} (not GET); CSRF + ReAuth
Enable / disableAuth’d POST /manage/2fa (TwoFactorRequest)Auth’d POST /auth/manage/2fa (same Identity body); CSRF + ReAuth
CSRF on POSTNot required by MapIdentityApiRequired (RequestVerificationToken)
Step-upNot built inReAuth required (confirmIdentity, then cookie or X-AuthEndpoints-Reauth)
enable + resetSharedKeyAvoid togetherDo not send together (validation problem)
Login with 2FAtwoFactorCode / twoFactorRecoveryCode on LoginSame fields on POST /auth/login

Client steps: Turn on two-factor authentication and Require step-up before sensitive actions.

After these four flows

AuthEndpoints also maps manage info, ReAuth routes, and optional passkeys/JWT. Stock MapIdentityApi does not include passkeys, ReAuth, cookie logout, or csrfToken. Those gaps are covered in What MapIdentityApi maps and the sections after it. Compose only the modules you need when the password facade is too much. See Build a custom auth stack and Identity management module.