AuthEndpoints vs MapIdentityApi and others
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.
| Method | Path |
|---|---|
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.
| Stack | Route | What logout ends |
|---|---|---|
| Cookie (password facade default) | POST /auth/logout | Application, external, two-factor user-id, remember-client, and ReAuth cookies. Requires a signed-in user and a CSRF token. |
| Identity bearer | POST /auth/logout | Those same cookies. Bearer access and refresh tokens stay valid until they expire. Requires a signed-in user. No CSRF token. |
| JWT | POST /auth/logout | The 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:
| Module | What it adds |
|---|---|
MapIdentityManagementApi | Register, confirm email, resend, forgot/reset password, manage info, set password, 2FA, ReAuth |
MapPasswordEndpoints | Register, forgot/reset password, and login for cookie or Identity bearer. PasswordLoginMode.None omits login. |
MapConfirmEmailEndpoints | GET /confirmEmail and POST /resendConfirmationEmail, once per endpoint name |
MapAccountManagementEndpoints | Manage info, set password, 2FA, auth methods, and POST /confirmIdentity |
MapCookieAuthEndpoints | Cookie POST /login, POST /logout, GET /csrfToken |
MapCookieSessionEndpoints | Cookie POST /logout and GET /csrfToken |
MapBearerAuthEndpoints | Identity bearer POST /login, POST /refresh, POST /logout |
MapBearerSessionEndpoints | Identity bearer POST /refresh and POST /logout |
MapJwtAuthEndpoints | JWT POST /create, POST /refresh, GET /verify, POST /logout, GET /csrfToken |
MapJwtPasswordEndpoints | JWT POST /create |
MapJwtSessionEndpoints | JWT refresh, verify, logout, and CSRF token |
MapPasskeyEndpoints | Passkey register, login, and credential management |
MapPasskeySignInEndpoints | Passkey register and login, plus confirm-email on the parent group when that name is new |
MapPasskeyManagementEndpoints | Signed-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.
| Stack | What login returns | Refresh |
|---|---|---|
| Cookie (password facade default) | Application cookie. Empty body. | The browser sends the cookie. |
| Identity bearer | Opaque accessToken and refreshToken in the body | POST /auth/refresh with { "refreshToken" } |
| JWT | JWT accessToken in the body, refresh token in the AuthEndpoints.Jwt.RefreshToken cookie | POST /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 API | AuthEndpoints password facade | |
|---|---|---|
| Route | POST /register (or POST /identity/register with MapGroup) | POST /auth/register |
| Body | Identity register (email, password) | Same Identity body |
| CSRF | Host policy (endpoint does not require antiforgery by default) | Not required (RequireAntiforgery is not on register) |
| Duplicate email | 200 (no enumeration) | 200 (no enumeration) |
| Confirmed-account policy | Host Identity options | RequireConfirmedAccount default true |
After 200 | Not signed in | Not signed in (200 ≠ session) |
| Confirm | GET …/confirmEmail?userId&code | GET /auth/confirmEmail?userId&code, then login. Optional ConfirmEmailRedirectUri → 302 with status / flow |
| Rate limit | Host-owned | Built-in account rate limits |
Client flow: register → check email → confirm → login. Steps: Register users.
Login
| Stock Identity API | AuthEndpoints password facade | |
|---|---|---|
| Route | POST /login (or under your MapGroup) | POST /auth/login |
| Handler | Identity Login | Shared password pipeline, finished by the Cookie completer |
| Body | Identity LoginRequest | Same (email, password, optional 2FA fields) |
| Default success | Identity bearer tokens (AccessTokenResponse) | Application cookie only (no bearer): empty body + Set-Cookie (TypedResults.Empty). Session when the flag is omitted |
| Cookie query flags | useCookies / useSessionCookies select cookie vs bearer | Only useSessionCookies (useCookies ignored). Persistent: ?useSessionCookies=false |
| CSRF on login | Not required | Not required |
| Logout | Not in MapIdentityApi | POST /auth/logout (auth + CSRF) |
| CSRF helper | Host-owned | GET /auth/csrfToken for logout, manage, ReAuth, resend |
| Lockout | Identity lockout | Lockout + 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 API | AuthEndpoints password facade | |
|---|---|---|
| Forgot | POST …/forgotPassword { email } → always 200 | POST /auth/forgotPassword → always 200 |
| CSRF / session on forgot | Not required | Not required |
Your IEmailSender<TUser> | Same (Production rejects Identity's no-op sender) | |
| Reset code | From mail | Base64Url token from the sender; send that value as resetCode |
| Reset | POST …/resetPassword { email, resetCode, newPassword } | Same Identity body on /auth/resetPassword |
| CSRF / session on reset | Not required | Not required |
| Then | POST …/login | POST /auth/login |
Client steps: Reset a forgotten password.
Two-factor authentication
| Stock Identity API | AuthEndpoints password facade | |
|---|---|---|
| Status | No GET — use POST /identity/manage/2fa (response includes sharedKey / flags) | GET /auth/manage/2fa → isTwoFactorEnabled and recoveryCodesLeft |
| Shared key | On stock POST response (TwoFactorResponse.sharedKey) | Mint/read via POST /auth/manage/2fa + {} (not GET); CSRF + ReAuth |
| Enable / disable | Auth’d POST /manage/2fa (TwoFactorRequest) | Auth’d POST /auth/manage/2fa (same Identity body); CSRF + ReAuth |
CSRF on POST | Not required by MapIdentityApi | Required (RequestVerificationToken) |
| Step-up | Not built in | ReAuth required (confirmIdentity, then cookie or X-AuthEndpoints-Reauth) |
enable + resetSharedKey | Avoid together | Do not send together (validation problem) |
| Login with 2FA | twoFactorCode / twoFactorRecoveryCode on Login | Same 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.