Upgrade to 4.0Changelog
Reference

Identity bearer sign-in module

Set up Identity bearer token login, refresh, and logout for mobile apps and token clients, and decide when to use bearer tokens instead of JWT.

ASP.NET Core Identity bearer token sign-in (not JWT). Pair with Identity management.

This module maps Identity Login. The password facade does not map these routes, and Session IdentityBearer fails its validation. Compose AddBearerAuthEndpoints and MapBearerAuthEndpoints.

Identity bearer is for mobile apps, and for browsers that keep the access token in localStorage or sessionStorage and send it on the Authorization: Bearer header. It is not a cookie session. If a host moves that token into a cookie and reads it from OnMessageReceived, unsafe requests need a CSRF token. The filter does not detect that cookie. Send RequestVerificationToken for those clients. This stack does not map a token route; the host has to map one. Cookie-based browser auth should use the cookie or JWT stack instead. The JWT stack maps GET /auth/csrfToken.

When to choose bearer vs JWT

StackUse when
Identity bearerYou want Identity's built-in access/refresh token format
JWTYou want JWT Bearer auth + HttpOnly refresh cookie with hashed storage and reuse detection

DI

builder.Services.AddBearerAuthEndpoints(); // ReAuth schemes + rate limits

Map

app.MapGroup("/auth").MapBearerAuthEndpoints<AppUser>();

The examples on this page use the prefix /auth. A host that also maps a cookie session puts the bearer routes on a second prefix, such as /bearer, because both sessions map POST /logout.

MapBearerAuthEndpoints maps Identity bearer POST /login and then MapBearerSessionEndpoints. Refresh and logout without password login:

builder.Services.AddBearerSessionEndpoints();
app.MapGroup("/auth").MapBearerSessionEndpoints<AppUser>();

AddBearerAuthEndpoints registers AddPasswordEndpoints, AddBearerSessionEndpoints, and AddAccountManagementEndpoints. A missing AddPasswordEndpoints or AddBearerSessionEndpoints throws InvalidOperationException when the matching map runs. The message names the Add* to call.

Routes

MethodPathNotes
POST/loginLogin; Identity bearer tokens (AccessTokenResponse) when both query flags are omitted; rate-limited
POST/refreshRefresh access token
POST/logoutRequires authorization

Login query string

Issues an application cookie when useCookies or useSessionCookies is true. Persistent when useCookies is true and useSessionCookies is not true. Neither flag → Identity bearer tokens (AccessTokenResponse).

QueryResult
neither flagIdentity bearer tokens
useCookies=true (and useSessionCookies not true)persistent application cookie
useSessionCookies=truesession application cookie

These flags apply to Login and to the default passkey completer. They do not apply to cookie password login: LoginCookie, or the Cookie completer on the password facade. See Cookie auth and Passkeys.

Logout

POST /logout requires authorization. It signs out cookies only and does not revoke Identity bearer tokens. Tokens remain valid until they expire.

Antiforgery

The antiforgery filter skips CSRF only when the request carries a non-empty Authorization: Bearer <token> header, the Identity bearer or JWT bearer scheme authenticates, and the application cookie does not. A token delivered only by a cookie still requires CSRF. Hosts that read the token from a cookie send the CSRF token. See Antiforgery (CSRF) rules.

MapBearerAuthEndpoints does not map a /csrfToken route. Anonymous passkey ceremonies mapped for Identity bearer (requestOptions, register/options, register, login) do not require a CSRF token. Signed-in passkey changes still do. An Authorization: Bearer access token skips that check. Cookie callers, including useCookies=true, still send the token. The Identity ceremony state lives in the TwoFactorUserIdScheme cookie (Identity.TwoFactorUserId). That cookie is single-use state, not a credential, and clients must send it between the options call and the verify call. login and register can also set an application cookie when useCookies or useSessionCookies is true.

A cookie session and JWT with cookie refresh transport still require the token. The shared POST /passkeys/register/options map keeps the check because a cookie session uses that route.