skip to content

In ASP.NET Core, what do AddIdentityApiEndpoints and MapIdentityApi provide, and how do the bearer tokens /login returns differ from JWTs issued by an identity provider?

level: seniorimportance: should knowfreq 40%

answer

  1. JSON endpoints instead of Razor pages
  2. /register, /login, /refresh and more
  3. ?useCookies=true switches to the cookie
  4. Identity.Bearer is not a JWT
  5. IEmailSender<TUser> defaults to a no-op

basics

~20 s

AddIdentityApiEndpoints registers Identity with a bearer-token scheme and cookies; MapIdentityApi maps JSON endpoints such as /register, /login and /refresh. Its tokens are Data Protection–protected tickets readable only by the same app, not JWTs other APIs can validate.

solid answer

~40 s

`AddIdentityApiEndpoints<TUser>()` (since ASP.NET Core 8) registers `AddIdentityCore` plus `SignInManager`, default token providers, a default no-op `IEmailSender<TUser>`, a bearer-token scheme `Identity.Bearer` and the Identity cookies behind a composite scheme that tries the bearer token first, then the cookie. `app.MapIdentityApi<TUser>()` maps `POST /register`, `/login`, `/refresh`, `GET /confirmEmail`, `POST /resendConfirmationEmail`, `/forgotPassword`, `/resetPassword` and the authorized `/manage/2fa` and `/manage/info`. `/login` signs in with `lockoutOnFailure: true`; with `?useCookies=true` it sets the cookie, otherwise it returns `tokenType`, `accessToken`, `expiresIn` and `refreshToken`. Those tokens are **not JWTs**: they are authentication tickets protected with Data Protection (one hour for access, 14 days for refresh by default), so only this app can read them. It is meant for a first-party SPA or mobile client, not as a token server.

code

http · 9 lines
http
POST /account/login HTTP/1.1
Content-Type: application/json

{ "email": "[email protected]", "password": "Comp0st-heap!" }

HTTP/1.1 200 OK
Content-Type: application/json

{ "tokenType": "Bearer", "accessToken": "CfDJ8...", "expiresIn": 3600, "refreshToken": "CfDJ8..." }

go deeper

for a junior

Recall the two calls, that they give JSON endpoints for register and login, and that ?useCookies=true chooses a cookie instead of a token.

for a middle

List the endpoints, the composite bearer-then-cookie scheme, the AccessTokenResponse fields and the one-hour and 14-day defaults.

for a senior

Explain why the tokens are Data Protection tickets rather than JWTs, what that rules out, the no-op e-mail sender, and the lockout behaviour of /login.

for a principal

Decide when the built-in endpoints are enough for a first-party client and when the system needs a real identity provider issuing JWTs.

## What problem it solves Identity's original UI is server-rendered Razor Pages. A single-page app or mobile client calling the same backend needs JSON endpoints instead. **Identity API endpoints**, added in ASP.NET Core 8, provide them in two calls: ```csharp builder.Services.AddIdentityApiEndpoints<GardenUser>() .AddEntityFrameworkStores<GardenDbContext>(); builder.Services.AddAuthorization(); var app = builder.Build(); app.MapGroup("/account").MapIdentityApi<GardenUser>(); ``` ## What `AddIdentityApiEndpoints` registers - `AddIdentityCore<TUser>` plus `AddApiEndpoints()`, which adds `SignInManager`, `AddDefaultTokenProviders` and a default `IEmailSender<TUser>` that forwards to a **no-op** `IEmailSender`. - A bearer-token handler under the scheme **`Identity.Bearer`** (`AddBearerToken`). - The Identity cookies (`AddIdentityCookies`). - A composite default scheme, `Identity.BearerAndApplication`, that authenticates with the bearer token when an `Authorization` header is present and otherwise falls back to the `Identity.Application` cookie; it is the default scheme for the app. ## The endpoints `MapIdentityApi` maps | Endpoint | Purpose | |---|---| | `POST /register` | create a user (needs a store that supports e-mail) | | `POST /login` | sign in; token or cookie | | `POST /refresh` | swap a refresh token for a new access token | | `GET /confirmEmail` | confirm the address from the e-mailed link | | `POST /resendConfirmationEmail` | send the link again | | `POST /forgotPassword`, `POST /resetPassword` | reset flow with a Base64url-encoded code | | `POST /manage/2fa`, `GET`/`POST /manage/info` | account management; require authorization | The .NET 8 release notes describe only `/register` and `/login`; the shipped method maps all of the above. ## `/login` in detail - Body: `email`, `password`, optional `twoFactorCode` or `twoFactorRecoveryCode`. - It calls `PasswordSignInAsync` with **`lockoutOnFailure: true`**, so lockout options apply. - `?useCookies=true` signs in with the persistent `Identity.Application` cookie, and `?useSessionCookies=true` with a session cookie; the response body is then empty. - Otherwise the response is an `AccessTokenResponse`: `tokenType` `"Bearer"`, `accessToken`, `expiresIn` (seconds) and `refreshToken`. - Failure is a 401 ProblemDetails whose detail names the `SignInResult`, such as `LockedOut` or `NotAllowed`. ## Why the tokens are not JWTs The bearer handler serialises the `ClaimsPrincipal` into an authentication ticket and protects it with **Data Protection**, the same mechanism that protects cookies. Consequences: 1. **Opaque.** The client cannot read claims from it, and there is no signature another service can check with public keys. `AddJwtBearer` in another API cannot validate it. 2. **Same-app only.** Any instance sharing the app's Data Protection keys can read it; nothing else can. 3. **Lifetimes from `BearerTokenOptions`.** `BearerTokenExpiration` defaults to one hour and `RefreshTokenExpiration` to 14 days. 4. **Refresh re-checks the user.** `/refresh` validates the security stamp, so a password change stops further refreshes. The documentation states the intent plainly: these custom tokens serve simple first-party clients that cannot use cookies; they are not a full identity provider or token server. If several APIs or third parties must accept the tokens, use a real OpenID Connect provider and `AddJwtBearer`. ## Gaps to plan for on the garden site - **E-mail does nothing by default.** Register your own `IEmailSender<GardenUser>` or confirmation and reset messages are silently dropped. - **No passkey or external-login endpoints.** Passkeys need your own endpoints around `SignInManager`. - **The route prefix is yours.** Without `MapGroup`, `/login` sits at the site root. - **The endpoints are fixed.** You cannot add fields to `/register`; teams that need a custom registration body write their own endpoint with `UserManager`.

  • Can a second API in the same solution validate these access tokens with AddJwtBearer?
    No. They are not JWTs and carry no signature for public-key validation. Only an app that registers the same `Identity.Bearer` handler and shares the issuing app's Data Protection keys and application name can unprotect them. For tokens several services accept, issue JWTs from an OpenID Connect provider.
  • Why does a newly registered user never receive the confirmation e-mail?
    `AddIdentityApiEndpoints` registers a default `IEmailSender<TUser>` that forwards to a no-op `IEmailSender`, so `/register` and `/resendConfirmationEmail` succeed while sending nothing. Register a real `IEmailSender<TUser>` implementation in DI.

  • MapIdentityApi issues standard JWTs that any API can validate.
  • MapIdentityApi maps only /register and /login.
  • /login with ?useCookies=true returns both a cookie and an access token.
  • Confirmation e-mails are sent through SMTP settings by default.
  • MapIdentityApi is a drop-in replacement for an OpenID Connect provider.

Assumes ASP.NET Core 10; AddIdentityApiEndpoints and MapIdentityApi arrived in ASP.NET Core 8, and the 8.0 release notes list only /register and /login although the method maps more.